Version information
This version is compatible with:
- Puppet Enterprise 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
- Puppet >= 4.6.0 < 5.0.0
- ,
Start using this module
Add this module to your Puppetfile:
mod 'simp-simp_gitlab', '0.3.0'
Learn more about managing modules with a PuppetfileDocumentation
Table of Contents
Description
This module provides profiles for integrating GitLab Omnibus with SIMP.
This is a SIMP module
This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.
It is designed to be used within a larger SIMP ecosystem, but it can be used independently:
- When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
- If used as an independent module, all SIMP-managed security subsystems are
disabled by default and must be explicitly opted into by administrators.
Please review the parameters in
simp/simp_options
for details.
If you run into problems, please let us know by filing an issue at https://simp-project.atlassian.net/.
Setup
What simp_gitlab
affects
This module is a profile that integrates Gitlab with SIMP. It makes extensive
use of the component module vshn/gitlab
. It is important to
note that vshn-gitlab
configures the GitLab Omnibus's /etc/gitlab/gitlab.rb
and runs gitlab-ctl reconfigure
.
As a profile module, simp_gitlab
has a few functions:
- Integrate SIMP and SIMP's global catalysts with GitLab Omnibus
- Supported SIMP Options (global catalysts):
-
simp_options::trusted_nets
-
simp_options::firewall
-
simp_options::pki
-
simp_options::ldap::*
-
- Intentionally unimplemented:
simp_options::selinux
― The GitLab Omnibus installer appears to handle SELinux correctlysimp_options::tcpwrappers
― nothing in Omnibus is linked to TCP Wrappersimp_options::auditing
― nothing in Omnibus needs special auditd logic
- Deferred:
simp_options::fips
― GitLab Omnibus ships with a version of OpenSSL that does not support FIPS modesimp_options::syslog
(not clear that we want to support this outside ofee
)
- SIMP integrations:
- Open access for a local
git
SSH user- set up a SIMP
pam::access::rule
to permit GitLab's localgit
user - configures
sshd
such that the GitLab's localgit
user's SSH authorized keys file path is managed only by the GitLab Omnibus installer.
- set up a SIMP
- The postfix service that comes with GitLab Omnibus is disabled in favor
of the SIMP
postfix
module.
- Open access for a local
- Supported SIMP Options (global catalysts):
- Ensure that GitLab Omnibus can be installed without internet access
- This requires a local mirror of the Gitlab repositories
- Simplify GitLab configuration for common scenarios
- GitLab
- GitLab + Omnibus version of NGINX
- Mattermost
- GitLab CI runner
- Intentionally unimplemented:
- Prometheus
- (Omnibus's integrated Prometheus app monitoring requires Gitlab Omnibus to be installed within a docker container)
- GitLab CI Runner (docker)
- Prometheus
- Permit customization of GitLab Omnibus
- Satisfy as many compliance-relevant criteria as possible
FIXME: Ensure the What simp_gitlab affects section is correct and complete, then remove this message!
mention:
- A list of files, packages, services, or operations that the module will alter, impact, or execute.
- Dependencies that your module automatically installs.
- Warnings or other important notices.
Setup Requirements
If using this module from an isolated network, ensure that package and repo
management are disabled from the module, and that the gitlab-ce
or
gitlab-ee
package is installed. Be sure that the $::simp_gitlab::edition
parameter is set to the correct edition.
Beginning with simp_gitlab
The most basic GitLab usage within a SIMP-managed infrastructure where all
simp_options::
are present:
include 'simp_gitlab'
Usage
A basic GitLab setup using PKI
class { 'simp_gitlab':
trusted_nets => [
'10.0.0.0/8',
'192.168.21.21',
'192.168.21.22',
'127.0.0.1/32',
],
pki => 'simp',
firewall => true,
}
Passing custom parameters to vshn-gitlab
Parameters for vshn/gitlab
can be passed in directly using the
(Hash) $simp_gitlab::gitlab_options
parameter.
Warning: $simp_gitlab::gitlab_options
parameters that conflict with the
rest of simp_gitlab
may lead to undefined behavior / broken systems.
Hint: Many of the data structures used by vshn/gitlab
's
parameters are documented at
https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template
# Name the local git user account `gitlab` (instead of the default `git`)
class { 'simp_gitlab':
trusted_nets => $simp_options::trusted_nets
pki => 'simp',
firewall => true,
gitlab_options => {
'user' => {
'username' => 'gitlab',
'group' => 'gitlab',
}
},
}
Configuring Nginx
simp_gitlab
configures the GitLab's internal Nginx server to look for
additional .conf
files under /etc/gitlab/nginx/conf.d/
.
If you need to configure the main Nginx server, use a file
resource from your
own profiles to establish a new .conf
file.
Reference
Please refer to the inline documentation within each source file, or to the module's generated YARD documentation for reference material.
Further Reference for munging GitLab Omnibus
- GitLab Omnibus
- documentation: https://docs.gitlab.com/omnibus/README.html
- architecture: https://docs.gitlab.com/omnibus/architecture/README.html
- source: https://gitlab.com/gitlab-org/omnibus-gitlab
- optional services:
- Mattermost (chat): https://docs.gitlab.com/omnibus/gitlab-mattermost/README.html
- Prometheus (monitoring): https://docs.gitlab.com/ce/administration/monitoring/prometheus/index.html
- GitLab Docker images: https://docs.gitlab.com/omnibus/docker/README.html
- vshn/gitlab component module:
- Security & compliance
Limitations
Gitlab's LDAP TLS is configured to re-use Omnibus' trusted-certs/
instead of ca_file
simp_gitlab
configures the GitLab Rails server LDAP TLS settings to use the
Omnibus trusted_certs (built from /etc/gitlab/trusted-certs
) instead of its
own ca_file
option.
The LDAP ca_file
setting is known to cause problems elsewhere in GitLab
SSL. There is a (currently undocumented)
workaround to these issues: GitLab's LDAP TLS will re-use
the GitLab Omnibus trusted-certificates/
directory―but only when the LDAP
ca_file
option has not been set
The drawback to this solution is that GitLab's LDAP client must share the same TLS settings as GitLab's web server―which is something that we try to keep distinct, as there could be situations in which their configurations legitimately vary.
GitLab
Puppet runs can fail if GitLab Omnibus's internal services don't start in time
Note: These are limitations of upstream components
-
The Exec that runs
gitlab-ctl reconfigure
may take a long time start its internal services, particularly during the first run that installs GitLab. These services are internal to the GitLab Omnibus installation and are not registered with the host OS or the Puppet providers forservice
. It is possible for the services to take so long to start in the background that dependencies withinvshn-gitlab
will fail.In these cases, it should be sufficient to simply run Puppet again after the services finish starting (status with
gitlab-ctl status
). -
If the GitLab Omnibus package is already installed but the
gitlab-runsvdir
service is stopped, the service will not start and catalog compilation will fail.
Nessus scans may incorrectly report CRIME vulnerability in GitLab
This is almost certainly a false positive―GitLab configures compression to 0
when HTTPS is enabled.
- See https://docs.gitlab.com/ce/security/crime_vulnerability.html for details.
Redis log warnings
Right now, redis logs these warnings (running in beaker/vagrant VMs):
# WARNING overcommit_memory is set to 0! Background save may fail under low
memory condition. To fix this issue add 'vm.overcommit_memory = 1' to
/etc/sysctl.conf and then reboot or run the command 'sysctl
vm.overcommit_memory=1' for this to take effect.
# WARNING you have Transparent Huge Pages (THP) support enabled in your kernel.
This will create latency and memory usage issues with Redis. To fix this issue
run the command 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' as
root, and add it to your /etc/rc.local in order to retain the setting after
a reboot. Redis must be restarted after THP is disabled.
Development
Please read our Contribution Guide.
Acceptance tests
This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:
bundle install
bundle exec rake beaker:suites
Please refer to the SIMP Beaker Helpers documentation for more information.
Environment variable TEST_GITLAB_CE_VERSION
TEST_GITLAB_CE_VERSION
is an environment variable that can be used
to specify the version of gitlab-ce to use in the acceptance tests.
When set, it must either a version string for a specific gitlab-ce
package version or 'latest' to indicate the latest available version.
TEST_GITLAB_CE_VERSION=latest bundle exec rake beaker:suites
Environment variable TRUSTED_NETS
TRUSTED_NETS
is an environment variable that may contain a comma-delimited
list of trusted networks to add to the gitlab SUT's firewall.
TRUSTED_NETS=192.168.11.0/24,10.0.2.2 bundle exec rake beaker:suites
Note: if the TRUSTED_NETS
configuration is too broad, it may cause
some acceptance tests (for denied clients) to fail.
Manually inspecting the SUT GitLab server with a web browser
Each nodeset in spec/acceptance/nodesets/
contains a commented-out
forwarded_ports:
section. If you want to use a web browser to manually
inspect the SUT GitLab server during any of the tests, uncomment this section
and add the NAT network router's IP address to the TRUSTED_NETS
variable.
For example:
TRUSTED_NETS=10.0.2.2 BEAKER_destroy=no bundle exec rake beaker:suites
Then, in a browser on the host machine, navigate to https://127.0.0.1:<port>
,
where <port>
is the forwarded port for the test being executed, i.e.,
8080, 8443, or 8777.
Note: If you need to login as the administrator to the GitLab instance,
use the login of root
and the password found on the GitLab server host at
/opt/puppetlabs/puppet/cache/simp/environments/production/simp_autofiles/gen_passwd/simp_gitlab_server.<your domain>
.
Interactive debugging using pry
Setting the environment variable PRY=yes
will cause the acceptance tests to
drop into a pry console under certain circumstances (usually just before
failures in examples with complex or hard-to-debug state). This will
effectively pause the test, to allow you to debug.
TRUSTED_NETS=10.0.2.2 BEAKER_destroy=no PRY=yes bundle exec rake beaker:suites
- Wed Feb 28 2018 Liz Nemsick lnemsick.simp@gmail.com - 0.3.0
- Drop support for CentOS 6 in order to cleanly solve an intermittent problem in which the GitLab local user's authorized keys lock file could not be created.
- Modify sshd authorized keys file configuration so that the GitLab installer can manage the GitLab local user's authorized keys file and the directory in which it resides, independent of Puppet. Prior to this, both the GitLab installer (via Chef) and Puppet were simultaneously, but independently, managing the ownership, permissions, and selinux contexts of that authorized keys file and its directory. Since the desired settings for the directory were different, intermittent problems such as the GitLab user not being able to create its authorized keys lock file arose.
- Fri Dec 29 2017 Chris Tessmer chris.tessmer@onyxpoint.com - 0.3.0
- Configure LDAP TLS to use the Omnibus'
trusted-certs/
instead of the LDAPca_file
setting (see https://gitlab.com/gitlab-org/gitlab-ce/issues/37254#note_3894021) - Add
ldap_verify_certificates
parameter - Add
ldap_ssl_protocols
parameter - Fixed LDAP provider name sanitation
- Update deprecated LDAP encryption configurations for GitLab 9.4+
- Add acceptance tests for LDAP authentication
- Document acceptance test features
- Removed unused
syslog
parameter
- Wed Apr 26 2017 Chris Tessmer chris.tessmer@onyxpoint.com - 0.2.0
- Manage PAM access and SSH keys for local Git Omnibus
git
user - Update static assets
- Wed Apr 26 2017 SIMP Team <simp-project.com> - 0.1.0
- This is the initial code for a
simp_gitlab
module, which installs GitLab Omnibus and incorporates it into SIMP.
Dependencies
- herculesteam/augeasproviders_ssh (>= 2.5.0 < 3.0.0)
- simp/iptables (>= 6.0.1 < 7.0.0)
- simp/ntpd (>= 6.0.0 < 7.0.0)
- simp/pam (>= 6.0.0 < 7.0.0)
- simp/postfix (>= 5.0.0 < 6.0.0)
- simp/simplib (>= 3.3.1 < 4.0.0)
- simp/ssh (>= 6.3.0 < 7.0.0)
- simp/svckill (>= 3.2.1 < 4.0.0)
- puppetlabs/stdlib (>= 4.13.1 < 5.0.0)
- vshn/gitlab (>= 1.13.3 < 2.0.0)
simp_gitlab - SIMP profiles for GitLab Per Section 105 of the Copyright Act of 1976, these works are not entitled to domestic copyright protection under US Federal law. The US Government retains the right to pursue copyright protections outside of the United States. The United States Government has unlimited rights in this software and all derivatives thereof, pursuant to the contracts under which it was developed and the License under which it falls. --- Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.