Rollout Manual

[ Up ]

Introduction

Rollout is a system developed to manage UNIX servers. It is primarily focused towards Linux, but could be adapted to Solaris, HP-UX, AIX, etc.

It is written purely in Perl, and the configuration is also a Perl source file. Some Perl knowledge is required to edit the configuration, but copy-and-paste will probably suffice.

Overview

System Administration can generally be reduced to a set of steps, which must be completed in order. Some example steps include:

Copy files, create symlinks
Edit configuration files
Start / stop services
Add / modify users & groups
Install applications

The idea behind Rollout is to automate all these steps in a configurable way. Rollout is by design indempotent - it can be run many times on a single server and produce the same results.

Running Rollout

Rollout is self-installing on servers. The following command line will install rollout for the first time:

# URL=http://rollout.domain:port; wget -q -O- $URL/rollout | perl - -u $URL -o setup

After it's installed, it can be run just by calling rollout. You must however give a comment on the rollout command line. This should be a short reason for running Rollout.

The first run uses the -s flag, which runs rollout in safe mode. In this mode, all the steps are run but no changes are actually made. This is used to check that nothing bad will happen when it's run for real.

After the safe mode run has been checked, it can be run again without the -s flag, and all steps will be applied.

NOTE: The first run requires the Error perl module to already be installed.

Command-line Arguments

The following command line arguments are available:

Full	Short	Description
`verbose`	v	Increase verbosity
`quiet`	q	Don't print anything except fatal errors
`safe_mode`	s	Show what will be changed, but don't actually do anything
`url`	u	Set the base Rollout HTTP url. This defaults to http://rollout.domain:port. This option is saved in the rollout script, so only needs to be specified once.
`skip_step`	k	Specify a step to be skipped, may be specified multiple times. e.g. -k network -k sysctl
`hostname`	h	Rollout configuration for a different host. If -f network is provided, the hostname will be changed to match the host supplied
`force`	f	Force a dangerous step to be run. e.g. -f network
`step_help`	H	Get help for a particular step

Logging

Every Rollout run that is run without the -s flag will be logged by the 999-complete step. The default is to make a HTTP request to the rollout server and pass it the log. The sample complete.php script will receive the log and do nothing with it.

Configuration

The configuration for Rollout is stored in rollout.cfg as well as other files in the fragments directory. These files are Perl source, so they can be checked for correctness by running perl -c rollout.cfg.

A major design concept in the rollout configuration is inheritance. Since many devices will have similar configurations, they should inherit as much as possible using the inherits() configuration item. Each class in the inherits() section is also specified in the same config, and they can inherit from other classes. It's even possible to have a device directly inherit another device's configuration, but this would include everything, even network interfaces.

Because a single file can be very unwieldy for large configurations, most of the configuration should be done in fragments files. You can put all the configuration in rollout.cfg if you wish, but you'll end up with a very large file that's hard to maintain. Each of the files in the fragments directory will be evaluated before Rollout starts making any changes. The source distrubtion includes a sample fragment file fragments/internal, which you can use as a template.

A sample device configuration looks like this:

device kickstart => {
  inherits(RHEL4_i386, Web_Server), # Inherit the RHEL4_i386 and Web_Server classes
  interfaces => {
    eth0 => {
      dhcp => 'kickstart',                     # eth0 gets its IP by DHCP
      mac => '00:50:8B:E8:A0:6D',
      primary => 1,
    },
    eth1 => {
      ip => '10.0.0.1',                        # eth1 is statically defined on its own network
      netmask => '255.255.255.0',
      mac => '00:D0:B7:E3:5A:F4',
    },
  },
  nfs_share => {
    "/kickstart" => {                          # Share the /kickstart directory by NFS
      "10.0.0.0/24" => "ro,no_root_squash",    # Allow the private LAN to access the nfs share
    },
  },
  firewall_allow => [
    '# Rollout HTTP',                          # This comment is inserted directly into the rules list
    any => '8140',                             # Allow any host to connect to tcp port 8140
    admin => '80',                             # Allow the admin network to connect to tcp port 80
  ],
  packages => [
    'dhcp',                                    # Make sure the dhcp and rpm-devel packages are installed
    'rpm-devel',
  ],
};

Configuration Items

The following items are available for use in rollout.cfg and other configuration fragments in the fragments directory:

Item	Type	Description
`apt_base`	string	Specifies a URL that will be added to the APT sources.list for local packages
`crontab`	hash	A hash of cron.d files that will be created, with the entries for each file
`cvs`	cvs	Specifies which modules will be checked out of CVS, and where
`deb_options`	list	Allows preconfiguring deb packages before they are installed. Expert Option
`dir_check`	list	Creates directories and forces ownership & permissions
`file_append`	list	Appends lines to text files, replacing any lines that match. Can also run a command if the file is changed
`file_attr`	hash	Modifies owner, group and permissions on files
`file_extract`	hash	Downloads a tarball and extracts it to a directory
`file_install`	hash	Downloads a file and places it somewhere. Can also run a command if the file is changed
`file_modify`	list	Modifies existing files by applying regular expressions. Can also run a command if the file is changed
`firewall_allow`	list	Allows incoming ports in the firewall
`firewall_append`	list	Appends verbatim lines to the iptables configuration file
`firewall_deny`	list	Denies incoming ports in the firewall
`group`	hash	Ensures a system group exists
`hosts_append`	list	Appends a given line to the /etc/hosts file
`immutable_file`	list	Marks a certain file as immutable. This file will never be touched by any other steps
`interfaces`	hash	Defines configuration for the network interfaces
`inherits`	list	Specifies a list of classes that this device or class inherits configuration from
`nameservers`	list	Specifies the default nameservers in /etc/resolv.conf
`network`	string	Marks the device or class as part of a network, for the purposes of firewalls and host files
`nfs_mount`	hash	Mounts a NFS share locally
`nfs_share`	hash	Shares a local directory by NFS
`packages`	list	Provides a list of packages to be installed. These can be debs or rpms
`port_check`	list	Adds elements to /etc/services
`service`	hash	Ensures that system services are running/stopped and should be started/stopped on boot
`skip_steps`	list	Mark a list of steps that will never be executed for this device
`sudo`	hash	Allow users to run commands with sudo
`ssh_keys_add`	list	Adds the list of keys to root's authorized_keys file
`symlink`	hash	Ensures a symlink exists and its destination is correct
`sysctl`	hash	Adds the items to /etc/sysctl.conf and applies them. These are for kernel configuration
`user`	string	Ensures each user exists, has the correct password and is in the correct groups

Sample Run

The following is pasted directly from the terminal after running Rollout:

# rollout
001-setup
020-network
  Installing /etc/network/interfaces from text
  Modified /etc/resolv.conf by appending options timeout:5 attempts:2
  Network config is considered dangerous, changes won''t be applied unless you specify the "-f network" argument.
030-hosts
  Modified /etc/hosts by appending 172.16.40.54 mulberry
  Modified /etc/hosts by appending 172.16.40.184 kickstart
050-users
060-ssh_keys
  Installing /root/.ssh/authorized_keys from text
  Changing mode of /root/.ssh/authorized_keys to 644
150-packages
  Installing packages lshw
200-sysctl
  Modified /etc/sysctl.conf by appending net.ipv4.conf.all.log_martians = 1
  Modified /etc/sysctl.conf by appending net.ipv4.conf.all.accept_redirects = 0
  Modified /etc/sysctl.conf by appending net.ipv4.conf.all.send_redirects = 0
  Modified /etc/sysctl.conf by appending net.ipv4.conf.all.rp_filter = 1
  Modified /etc/sysctl.conf by appending net.ipv4.icmp_echo_ignore_broadcasts = 0
  Modified /etc/sysctl.conf by appending net.ipv4.tcp_syncookies = 1
  Modified /etc/sysctl.conf by appending net.ipv4.conf.all.accept_source_route = 0
210-cvs
211-svn
240-dir_check
240-file_extract
250-file_install
  Installing /etc/pam_ldap.conf from http://rollout.domain/conf/pam_ldap.conf
  Installing /etc/libnss-ldap.conf from http://rollout.domain/conf/libnss-ldap.conf
  Changing mode of /etc/libnss-ldap.conf to 600
  Installing /etc/ntp.conf from http://rollout.domain/conf/ntp.conf
  Installing /etc/resolv.conf from http://rollout.domain/conf/resolv.conf
  Changing target of symlink /usr/local/bin/vis to /usr/local/bin/viw
270-port_check
300-logrotate
400-ulimit
450-python
600-sudo
700-nfs
800-file_append
801-file_comment
802-file_modify
  Modified /etc/nsswitch.conf with s/^passwd:.*/passwd:  compat ldap/, s/^group:.*/group:  compat ldap/
810-file_attr
820-smart
830-snmp
850-cron
900-services
970-motd
980-queued
999-complete

Steps

Every step has built-in help, which you can get on a client with:

# rollout -H timezone
NAME
    070-timezone

DESCRIPTION
    Set the timezone of the machine.

EXAMPLE
      device sample => {
        timezone => "Australia/Sydney",
      };

OPTIONS
    timezone
        This should be a file or a directory that exists in
        "/usr/share/zoneinfo" or "/usr/share/lib/zoneinfo".

COPYRIGHT
    Copyright 2010 David Parrish

On the rollout server, you can get the same help using:

# perldoc /usr/local/rollout/steps/070-timezone
NAME
       070-timezone

DESCRIPTION
       Set the timezone of the machine.

EXAMPLE
         device sample => {
           timezone => "Australia/Sydney",
         };

OPTIONS
       timezone
           This should be a file or a directory that exists in "/usr/share/zoneinfo" or "/usr/share/lib/zoneinfo".

COPYRIGHT
       Copyright 2010 David Parrish