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. simp config
uses theproduction
Puppet Environment by default. If you want to use a different intial environment, see HOWTO Use an Alternate ‘simp config’ Environment.
- 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 andsudo
toroot
.- If you installed from the ISO
- Log in as
simp
. - Run
sudo su - root
.
- Log in as
- If you installed from RPM
- Create a local user that can escalate to
root
and use it to access theroot
account.
- Create a local user that can escalate to
- If you installed from the ISO
- Run
simp config
and configure the system as prompted.- These settings will be used to set up files appropriate for bootstrapping the system.
- For each setting:
- Press Enter to keep the recommended value or enter your desired value.
- For each setting:
- These settings will be used to set up files appropriate for bootstrapping the system.
- For more details about
simp config
’s installation variables and actions, see Advanced Configuration.Note
If you see a message about ‘simp bootstrap’ being ‘locked’, follow the steps in Prevent Lockout from the SIMP Server during RPM Installation:
Run
simp bootstrap
.If your SIMP server is on a virtual machine, or slow system, 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 the timeout to 10 minutes:
$ simp bootstrap -w 10
Note
If the bootstrap progress bars of each Puppet run are of equal length, a problem has probably occurred due to an error in SIMP configuration. Refer to the previous step and make sure that all configuration options are correct.
You can debug issues by either looking at the log files in
/root/.simp
or by runningpuppet agent -t --masterport=8150
.Run
reboot
to restart your system and apply the necessary kernel configuration items.
After rebooting, SIMP-managed security settings have been applied and the SIMP server is ready for site-specific configuration.
To su
to root
from the simp
user, you must now use sudo su - root
.
4.2.3. Next Steps¶
- To continue configuring the system, move on to the next section in the SIMP User Guide, Client Management.
The following are links to other information in the user guide that are answers to questions sometimes asked at this time:
- To learn more details about how your system has just been configured see Advanced Configuration.
- To add additional simp modules or you own site modules to the environment Updating an Existing Environment
- To extract the Full OS to the yum server see HOWTO Use unpack_dvd to Extract the Full OS RPM Package Set
4.2.4. Prevent Lockout from the SIMP Server during RPM Installation¶
By default, SIMP:
- Disables remote logins for all users.
- Disables
root
logins at the console.
If either of the following scenarios applies, you must enable sudo
and
ssh
access for a local user. If you do not do this, you may lose access to
your system.
- Scenario 1:
Console access is available, but not allowed. Only the
root
user (and no other user account) is available.- This generally occurs when SIMP is installed from RPM and the user accepts
simp config
’s default value foruseradd:securetty
(an empty array).
- This generally occurs when SIMP is installed from RPM and the user accepts
- Scenario 2:
Console access is not available, and the administrative user’s
ssh
access has not yet been enabled permanently via Puppet.- This generally occurs when SIMP is installed from RPM on cloud systems.
In either of these scenarios, simp config
will issue the following warning
and write a lock file to prevent simp bootstrap
from running:
'simp bootstrap' has been locked due to potential login lockout.
* See /root/.simp/simp_bootstrap_start_lock for details
The remainder of this document provides instructions on ensuring that a local user has the appropriate level of system access.
After you address all issues identified in
/root/.simp/simp_bootstrap_start_lock
(see
Resolve Other Issues in the Bootstrap Lock File), you should remove the file and
continue with the bootstrap
process.
4.2.4.1. Ensuring Local User Access¶
If you already have an unprivileged account:
- Replace
userx
with your current non-root username throughout the example code.
- Replace
If you do NOT already have an unprivileged account:
- Create a local user account, using
useradd
.- This example assumes the local user is named
userx
. - Be sure to set the user’s password if the user is logging in with a password!
- This example assumes the local user is named
- Create a local user account, using
- Run
sudo su - root
- Run
cd /etc/puppetlabs/code/environments/production/data/hosts
- Add the following to
<puppetserver fqdn>.yaml
# Add sudo user rules sudo::user_specifications: # Any unique name userx_su: # The users to which to apply this sudo rule user_list: - userx # The commands that the user is allowed to run cmnd: - ALL # Whether or not the user must use a password passwd: false # Add a PAM remote access rule pam::access::users: # The user to add userx: # Allow access from everywhere origins: - ALL
4.2.4.2. If Your Local User Uses an SSH Public Key¶
If the local user has an SSH public key available, copy the authorized_keys
file for that user to the SIMP-managed location for authorized keys
/etc/ssh/local_keys
:
mkdir -p /etc/ssh/local_keys chmod 755 /etc/ssh/local_keys cp ~userx/.ssh/authorized_keys /etc/ssh/local_keys/userx chmod 644 /etc/ssh/local_keys/userx
4.2.4.3. Resolve Other Issues in the Bootstrap Lock File¶
If any other issues are identified in /root/.simp/simp_bootstrap_start_lock
,
you must address them before removing the file.
- Currently, the only other issue
simp config
will identify is a possible misconfiguration of YUM repositories.simp config
will lock out bootstrap if it cannot find a few of the key packages needed for bootstrapping. Fix your yum repository configuration and then verify the fix using the verification instructions in the lock message.
4.2.4.4. Resume Bootstrap Operation and Verify User Access¶
Warning
DO NOT REBOOT BEFORE VERIFYING USER ACCESS USING AN ALTERNATE TERMINAL OR SSH SESSION
Remove the lock file and bootstrap the system
rm /root/.simp/simp_bootstrap_start_lock
simp bootstrap
puppet agent -t
The following items are not failures and can be ignored. All other errors or warnings should be addressed prior to proceeding:
- Reboot notifications.
- Warning/errors related to modules that manage services you have not
completely set up, such as
named
. svckill
warnings regarding services found that would be killed ifsvckill::mode
was set toenforcing
.
Verify user accesss
- Using a NEW SSH SESSION OR TERMINAL (do NOT close your working
session)
- Log in as
userx
sudo su - root
- Log in as
- Using a NEW SSH SESSION OR TERMINAL (do NOT close your working
session)
Warning
If your new user cannot ssh into the server and sudo to
root
- DO NOT reboot the server until you resolve the problem!
- DO NOT log out of your primary work terminal unti you resolve the problem!
4.2.4.5. Finalization¶
Reboot your system to enact the kernel-level enforcement changes:
reboot
Re-verify system access:
- Log back in as
userx
sudo su - root
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
.