4.2. Initial SIMP Server Configuration¶
4.2.1. Introduction to the SIMP Utility¶
The simp
command provides a CLI intended to make the
configuration of the SIMP server straightforward and repeatable.
In these instructions, we will be using the config
and bootstrap
options of the simp
command
For a list of the commands simp
provides, type simp help
. Type
simp <Command> --help
for more information on a specific command.
simp config
sets up configuration required to bootstrap the SIMP server with Puppet. It asks questions, generates configuration files, and applies preliminary server configuration based on the answers. It records the options chosen in a file,/root/.simp/simp_conf.yaml
and generates a log file under/root/.simp/
.- You can use the
--dry-run
option to step through the questions without changing anything and then runsimp config -a /root/.simp/simp_conf.yaml
to apply the changes.
- You can use the
simp bootstrap
uses several targeted Puppet runs to configure the rest of the system and generates a log file under/root/.simp/
.
For more details about initial configuration provided by simp config
see
Advanced Configuration.
4.2.2. Configuring the SIMP Server¶
Warning
Puppet has problems when hostnames contain capital letters (SERVER-1809) — do not use them!
Log on as a user that can gain
root
access andsu
toroot
.- If you installed from the ISO, it created the
simp
user. Log in withsimp
and runsu -
. - If you installed from RPM, create a privileged user or log in as
root
. There will be instructions later about how to configure access for the privileged user on the SIMP server, so that after bootstrap, you are not locked out of the server. This step is essential on cloud instances.
- If you installed from the ISO, it created the
Run
simp config
and configure the system as prompted. (The--dry-run
option will run through all of the prompts without applying any changes to the system.)simp config
will prompt you with the follow:Ready to create the SIMP omni-environment?
Enteryes
.Ready to start the questionaire?
Enteryes
.
simp config
will then prompt you for system settings and apply them as appropriate for bootstrapping the system. When applicable,simp config
will present you with a recommendation for each setting. For each question:- Press Enter to keep a recommended value.
- Otherwise, enter your desired value.
When the questionnaire is finished and you are prompted with
Ready to apply?
Enteryes
to continue.
simp config
then applies the information and generates its configuration files.Important
If you have installed SIMP from RPM and see the following failure, go to the Prevent Lockout from the SIMP Server during RPM Installation section and follow the steps to configure a user that has
su -
capability.'simp bootstrap' has been locked due to potential login lockout.
* See /root/.simp/simp_bootstrap_start_lock for details
For more details about
simp config
’s installation variables and actions, see Advanced Configuration.
Run
simp bootstrap
.If your SIMP server is a virtual machine in a cloud, the default timeout for the Puppet server to start (5 minutes) may be too short. You will want to extend this time by using the
-w
option. For example, to extend that timeout to 10 minutes:simp bootstrap -w 10
Note
If the bootstrap finishes quickly and the progress bars of each Puppet run are of equal length, it is very likely that a problem has occurred due to an error in SIMP configuration. Refer to the previous step and make sure that all configuration options are correct.
If this happens, you can debug by either looking at the log files or by running
puppet agent -t --masterport=8150
.Run
reboot
to restart your system and apply the necessary kernel configuration items.
When your systems comes back up, SIMP-managed security settings have been applied
and the SIMP server (puppetserver
) is ready for site-specific configuration.
To su
to root
from the simp
user, you must now use sudo su -t root
.
Next steps:
- To continue configuring the system, move on to the next section in the SIMP User Guide, Client Management.
- To learn more details about what the
simp
utility just did to your system, see Advanced Configuration.
4.2.3. Optional: Extract the full OS RPM Package Set¶
The SIMP ISO only provides enough RPM packages to run a basic system. If you require additional stock OS packages, you can extract additional packages from vendor ISOs using the following procedure:
Log on as
simp
and runsu -
to gain root access.Run
puppet agent -t
to ensure system consistency.Copy the appropriate vendor OS ISO(s) to the server and unpack using the
unpack_dvd
utility. This will create a new directory tree under/var/www/yum/<OperatingSystem>
suitable for serving to clients.Run:
unpack_dvd CentOS-RHEL_MAJOR_VERSION-x86_64-DVD-####.iso
Ensure that subsequent yum operations are aware of the new RPM packages by refreshing the system’s yum cache:
Run:
yum clean all; yum makecache
4.2.4. Prevent Lockout from the SIMP Server during RPM Installation¶
Per security policy, SIMP, by default, disables login via ssh
for all users,
including root
, and beginning with SIMP 6.0.0, disables root
logins at
the console by default. So, if one of the following scenarios applies, you
should configure a local user for this server to have both su
and ssh
privileges, in order to prevent lockout from the system:
- Console access is available but not allowed for
root
and no other administrative user account has yet been created.- This can happen when SIMP is installed from RPM and the user accepts
simp config
’s default value foruseradd:securetty
(an empty array).
- This can happen when SIMP is installed from RPM and the user accepts
- Both console access is not available and the administrative user’s
ssh
access has not yet been enabled (permanently) via Puppet.- This can happen when SIMP is installed from RPM on cloud systems.
simp config
will issue a warning if it thinks this situation may be
possible and writes a lock file to prevent simp bootstrap
from running.
The warning looks like:
'simp bootstrap' has been locked due to potential login lockout.
* See /root/.simp/simp_bootstrap_start_lock for details
If you have access to the console, have the root
password, and have enabled
root
console access by setting useradd::securetty
in Hiera to a
valid tty (e.g., tty0
), you can simply remove the file
/root/.simp/simp_bootstrap_start_lock
and continue with the bootstrap
process.
Otherwise follow the instructions below to enable login from a local account,
and then remove /root/.simp/simp_bootstrap_start_lock
and continue with the
bootstrap process.
4.2.4.1. Configure Local User for Access¶
This example creates a manifest in a local module, mymodule
, in the
production
Puppet environment. See Puppet module documentation for
information on how to create a Puppet module.
Create a local user account, as needed, using
useradd
. This example assumes the local user isuserx
.- Be sure to set the user’s password if the user is logging in with a password.
- SIMP is configured to create a home directory for the user, if it does not exist when the user first logs in.
Create a
local_user.pp
manifest inmymodule/manifests
to enablesudo su - root
and allowssh
access for the user you created/selected:class mymodule::local_user ( Boolean $pam = simplib::lookup('simp_options::pam', { 'default_value' => false }), ) { sudo::user_specification { 'default_userx': user_list => ['userx'], runas => 'root', cmnd => ['/bin/su root', '/bin/su - root'] } if $pam { include '::pam' pam::access::rule { 'allow_userx': users => ['userx'], origins => ['ALL'], comment => 'The local user, used to remotely login to the system in the case of a lockout.' } } }
Create a mymodule/metadata.json file. It should look something like the following: See Puppet metadata documentation for more information on metadata.json files.
{ "name": "mymodule", "version": "0.0.1", "author": "Your name or group here", "summary": "Configures Local User for sudo access", "license": "Apache-2.0", "source": "Your gitlab url or local", "dependencies": [ { "name": "simp/pam", "version_requirement": ">= 6.0.0 " }, { "name": "simp/sudo", "version_requirement": ">= 5.1.0 " }, ], }
Make sure the permissions are correct on the module:
sudo chown -R root:puppet /etc/puppetlabs/code/environments/production/modules/mymodule sudo chmod -R g+rX /etc/puppetlabs/code/environments/production/modules/mymodule
Add the module to the SIMP server’s host YAML file class list:
Edit the SIMP server’s YAML file,
/etc/puppetlabs/code/environments/production/data/<SIMP server FQDN>.yaml
and add themymodule::local_user
to theclasses
array:classes: - mymodule::local_user
If the local user is configured to login with pre-shared keys instead of a password (typical cloud configuration), copy the
authorized_keys
file for that user to the SIMP-managed location for authorized keys/etc/ssh/local_keys
:sudo mkdir -p /etc/ssh/local_keys sudo chmod 755 /etc/ssh/local_keys sudo cp ~userx/.ssh/authorized_keys /etc/ssh/local_keys/userx sudo chmod 644 /etc/ssh/local_keys/userx
Add the module to the
Puppetfile
in theproduction
environment:Edit the
Puppetfile
used to deploy the modules,/etc/puppetlabs/code/environments/production/Puppetfile
, and add a line under the section that says “Add you own Puppet modules here”mod 'mymodule', :local => true
4.2.5. Advanced Configuration¶
The goal of simp config
is to allow the user to quickly configure the
SIMP server with minimal user input/operations. To that end simp config
sets installation variables based on information gathered from the user,
existing system settings, and SIMP security requirements. It then
applies the smallest subset of these system settings that is required to
bootstrap the system with Puppet. Both the installation variables and
their application via simp config
are described in subsections that
follow.
4.2.5.1. Installation Variables¶
This section describes the installation variables set by simp config
.
Although the table that follows lists all possible installation
variables, the user will not be prompted for all of them, nor will all of
them appear in the configuration files generated by simp config
. Some
of these variables will be automatically set based on other installation
variables, system settings, or SIMP security requirements. Others will
be omitted because either they are unnecessary for a particular site
configuration, or their defaults are appropriate. Also, please note
that variables beginning with cli::
are only used internally by
simp config
, itself. The cli::
variables are written to
simp_conf.yaml
, but not persisted to any Puppet hiera data files.
Important
- Not all the settings listed below may be able to be preset in a
configuration file input to
simp config
, via either-a <Config File>
or-A <Config File>
. Some settings for which you would not be prompted if you ransimp config
interactively may be automatically determined bysimp config
. - Passwords for which only hashed values are stored in the YAML
output of
simp config
must be input as hashed values in an input configuration file. simp config
behaves differently (asks different questions, automatically determines different settings) depending on the SIMP installation type. This is because it can safely assume certain server setup has been done, only if SIMP has been installed from the SIMP-provided ISO. For example, consider asimp
local user. When SIMP is installed from ISO,simp config
can safely assume that this user is the backup user installed by the ISO to prevent server lockout. As such,su
andssh
privileges for thesimp
user should be allowed. For non-ISO installs, however, it would not be prudent forsimp config
to grant just anysimp
user bothsu
andssh
privileges.simp config
detects that SIMP has been installed from a SIMP-provided ISO by the presence of/etc/yum.repos.d/simp_filesystem.repo
.
Tip
There are two simp config
options that are particularly useful:
--dry-run
will run through all of the prompts without applying any changes to the system. This is useful to:
- become familiar with the variables set by
simp config
without applying them- generate a configuration file to use as a template for subsequent
simp config
runs-a <Config File>
will load and apply a previously-generated configuration (aka the ‘answers’ file) in lieu of prompting for settings.
- This is useful to run on systems that will be rebuilt often.
- Please note, however: if you edit the answers file, only configuration settings for which you would be prompted by
simp config
can be modified in that file—any changes made to settings thatsimp config
automatically determines will be ignored.
If you want to understand what variables apply to your setup, run
simp config --dry-run
and examine the generated simp_conf.yaml
file. That file will contain both the settings and their documentation.
Variable | Description |
---|---|
cli::is_simp_ldap_server | Whether the SIMP server will also be a SIMP-provided LDAP server |
cli::network::dhcp | Whether to use DHCP for the network; dhcp to enable DHCP, static otherwise |
cli::network::gateway | Default gateway |
cli::network::hostname | FQDN of server |
cli::network::interface | Network interface to use |
cli::network::ipaddress | IP address of server |
cli::network::netmask | Netmask of the system |
cli::network::set_up_nic | Whether to set up the network interface; true or false |
cli::set_grub_password | Whether to set a GRUB password on the server; true or false |
cli::simp::scenario | SIMP scenario; simp = full SIMP system, simp_lite = SIMP system with some security features disabled for clients, poss = SIMP system with all security features disabled for clients |
cli::use_internet_simp_yum_repos | Whether to configure SIMP nodes to use internet SIMP and SIMP dependency YUM repositories |
grub::password | GRUB password hash |
puppetdb::master::config::puppetdb_port | Port used by the puppet database |
puppetdb::master::config::puppetdb_server | DNS name or IP of puppet database server |
simp_openldap::server::conf::rootpw | LDAP Root password hash |
simp_options::dns::search | Search domain for DNS |
simp_options::dns::servers | List of DNS servers for the managed hosts |
simp_options::fips | Enable FIPS-140-2 compliance; true or false; value automatically set to detected system FIPS status |
simp_options::ldap | Whether to use LDAP; true or false |
simp_options::ldap::base_dn | LDAP Server Base Distinguished Name |
simp_options::ldap::bind_dn | LDAP Bind Distinguished Name |
simp_options::ldap::bind_hash | LDAP Bind password hash |
simp_options::ldap::bind_pw | LDAP Bind password |
simp_options::ldap::master | LDAP master URI |
simp_options::ldap::sync_dn | LDAP Sync Distinguished Name |
simp_options::ldap::sync_hash | LDAP Sync password hash |
simp_options::ldap::sync_pw | LDAP Sync password |
simp_options::ldap::uri | List of LDAP server URIs |
simp_options::ntpd::servers | NTP servers |
simp_options::puppet::ca | FQDN of Puppet Certificate Authority (CA) |
simp_options::puppet::ca_port | Port Puppet CA will listen on |
simp_options::puppet::server | FQDN of the puppet server |
simp_options::sssd | Whether to use SSSD |
simp_options::syslog::failover_log_servers | IP addresses of failover log servers |
simp_options::syslog::log_servers | IP addresses of primary log servers |
simp_options::trusted_nets | Subnet used for clients managed by the puppet server |
simp::runlevel | Default system run level; 1-5 |
simp::server::allow_simp_user | Whether to allow local ‘simp’ user su and ssh privileges |
simp::yum::repo::local_os_updates::enable_repo | Whether to enable the SIMP-managed, OS Update YUM repository that the SIMP ISO installs on the SIMP server |
simp::yum::repo::local_os_updates::servers | YUM server(s) for SIMP-managed, OS Update packages |
simp::yum::repo::local_simp::enable_repo | Whether to enable the SIMP-managed, SIMP and SIMP dependency YUM repository that the SIMP ISO installs on the SIMP server. |
simp::yum::repo::local_simp::servers | YUM server(s) for SIMP-managed, SIMP and SIMP dependency packages |
sssd::domains | List of SSSD domains |
svckill::mode | Strategy svckill should use when it encounters undeclared services; enforcing = shutdown and disable all services not listed in your manifests or the exclusion file warning = only report what undeclared services should be shut down and disabled, without actually making the changes to the system |
useradd::securetty | A list of TTYs for which the root user can login |
4.2.5.2. simp config Actions¶
In addition to creating the three configuration, YAML files, simp config
performs a limited set of actions in order to prepare the system for
bootstrapping. Although the table that follows lists all possible
simp config
actions, not all of these actions will apply for all site
configurations.
Category | Actions Performed |
---|---|
Certificates | If no certificates for the host are found in
/var/simp/environments/production/site_files/pki_files/ files/keydist , simp config will use SIMP’s FakeCA
to generate interim host certificates. These certificates,
which are independent of the certificates managed by Puppet,
are required by SIMP and should be replaced by certificates
from an official Certificate Authority, as soon as
is practical. |
GRUB | When the user selects to set the GRUB password
simp config will set the password in the appropriate
grub configuration file, /etc/grub.conf or
/etc/grub2.cfg . After initial configuration, the GRUB
password can be managed with the simp-simp_grub module.
See Managing GRUB Users
for more information. |
LDAP | When the SIMP server is also a SIMP-provided LDAP server,
|
Lockout Prevention | When the SIMP server is installed from ISO, the install
creates a local
|
Network |
|
Puppet |
|
SIMP Hiera & Site Manifest |
|
YUM |
|
4.2.5.3. simp config Output¶
At the end of simp config
, when you answer yes
to Ready to apply?
,
simp config
generates three files:
/root/.simp/simp_conf.yaml
:- File containing all your
simp config
settings; can include additional settings related to ones you entered and other settings required for SIMP.
/etc/puppetlabs/code/environments/production/data/simp_config_settings.yaml
:- File containing global Hiera data relevant to SIMP clients and the SIMP server.
/etc/puppetlabs/code/environments/production/data/hosts/<server_fqdn>.yaml
:- The SIMP server’s host-specific Hiera configuration.
If you terminate simp config
before applying the configuration, it will
generate a file /root/.simp/.simp_conf.yaml
. This interim file (aka the
safety-save file), contains the answers up until the point you terminated
simp config
.