Context Navigation

How to Install Quattor with SCDB

This page contains a step-by-step installation guide for Quattor SCDB, a configuration database and its associated deployment tools. SCDB relies on several underlying services not specific to Quattor, like Apache, Subversion, DHCP, TFTP and installing SCDB involves configuring these underlying services for Quattor use. This is potentially site-specific but to illustrate the configuration process decribed here, this page contains command examples based on the following assumptions:

SVN server is svn.example.org. This clearly need to be updated to reflect your host/domain name.
SVN repository associated with SCDB can be accessed through URL http://svn.example.org/svn/quattor.
TFTP server root directory is the default, /tftpboot.

Also, for the sake of simplicity, the configuration steps for underlying services assume that these services are dedicated to Quattor. As stated in this guide, this is not at all a requirement. If you want to use an already existing service for Quattor, you'll need to tweak the proposed configuration to fit in your existing configuration. This may require information not present in this guide: in this case refer to the service documentation. If you have no specific constraint and you aren't familiar with these services, you are probably better to stick with a configuration as close as possible with the one used in examples.

Note : the installation process described below is as generic as possible, but the commands used in examples have been tested only on Scientific Linux version. They may need to be modified when underlying services like SVN or DHCP are hosted on another platform.

OS Installation

Quattor server requires a machine installed with a default server installation of any RH-based Linux distro. There is no specific requirements for the OS configuration itself: just check your installation options install an Apache web server.

The server can be installed by any mean available at the site (CD-Rom, Kickstart, imaging...). When Quattor server is ready, it will be possible to manage the server itself with Quattor, including OS upgrades.

Web Server Installation

The Quattor server needs to run a Web server to serve profiles, kickstart configuration files and execute the CGI script at end of installation to change PXE boot to local disk. In addition, it is recommended (but not necessary) to use this Web server for serving RPMs.

Web server installation requires nothing specific, just the configuration of a document root with enough space if you plan to serve RPMs and the configuration of CGIs. This Web server can be shared with other usages and you can use a specific virtual host instead of a dedicated server.

Apache is the recommended Web server (installation instructions here refer to Apache) and it can be installed from the OS distribution. Note that for subversion http mode, Apache version 2 or above is needed.

Apache Recommended Settings

SCDB has no strong requirement concerning Apache configuration. It generally uses 3 distinct URLs for 3 different purposes :

Profiles : machine profiles are served by one specific URL shared by all machines. The files there are XML files produces by the PAN compiler when executing ant deploy.
Kickstart configuration files : this URL is used to store the Kickstart configuration file for each machines. These files are produced by aii-shellfe --configure.
RPM packages : RPMs are grouped in repositories, each repository has its own URL. This is a common setting to have one common parent URL for all repositories but this is not at all a requirement.

Recommended setting for these 3 areas are :

Restrict access to profile and Kickstart configuration to IP adresses (or subnets) matching Quattor clients, as these files may contain sensitive information like encrypted passwords or MySQL passwords (cleartext).
Configure all these areas to ignore any index.html file and auto-indexing. This is particularly important for RPM repositories URLs, as presence of an index.html will prevent SCDB tools to get the list of RPMs in the repository.

Configuration for these areas is normally done by creating a file /etc/httpd/conf.d/quattor.conf with directives like the following one for each area (replace /path/to/area by your actual directoy name) :

<Directory /path/to/area>
    Options Indexes
    DirectoryIndex VeryUnlikelyDirectoryIndex.none
    AllowOverride None
</Directory>

It is also better to add the following directive in our /etc/httpd/conf.d/quattor.conf to work around a problem in some RPM versions:

<IfModule mod_setenvif.c>
  BrowserMatch "rpm/.*" nokeepalive force-response-1.0
</IfModule>

Note: if you are installing a new Apache server, don't forget to edit DocumentRoot in /etc/httpd/conf/httpd.conf to reflect your local configuration.`

Note: even though it is easily redone, it is better to backup quattor.conf file.

Subversion Server

There is no need for a Subversion server dedicated to Quattor. SCDB is just one repository from the Subversion point of view. If you already run a Subversion server, you can skip the installation part and go directly to the configuration part.

Subversion Installation and Configuration

There are many possible installation options for a Subversion server. The best is to install it as Apache module, anyway. There is no requirement for the Subversion server to run on a Linux machine, even if it is the installation option documented here. You can even choose to use a Subversion server outside of your site, if you think the network connection is good enough.

Note: Quattor has no requirement regarding the name of the directory where SVN repository is located, the URL associated with the repository. Even a repository non dedicated to SCDB (with already existing contents) can be used. The examples in this page are based on a repository created as part of the SCDB installation and associated with URL http://svn.example.org/svn/quattor. If you are not familiar with SVN and SVN management, you are probably better to use a configuration as close as possible to the examples.

If you need to install a Subversion server, the easiest is to install Apache using YUM. Another option is to retrieve the RPMs for Subversion from [http://subversion.tigris.org/project_packages.html Subversion site]. Don't forget to install the Apache module which is in a separate RPM.

A typical SVN installation with YUM is:

yum install subversion mod_dav_svn

After installing, you have to configure the Subversion server. Refer to Subversion web site for details. Configuration the SVN server typically involves:

Creation of directory which will contain the Quattor repository (this example uses /var/svn):
```
mkdir -p /var/svn
```

Create Subversion repository that will be used for Quattor SCDB (don't forget to backup this directory):

svnadmin create /var/svn/quattor
# Repository must be owned by Apache account
chown -R apache:apache /var/svn/quattor

Apache SVN module configuration (/etc/httpd/conf.d/subversion.conf) must be edited to configure URL used by SVN (examples in this page assume this is /svn) and bind it to the directory created at the previous step. A typical example, based on previously created repository (adjust paths to reflect your configuration) is:

<Location /svn>
   DAV svn
   SVNParentPath /var/svn

   AuthzSVNAccessFile security/svn-repositories-access

   AuthType        Basic
   AuthUserFile    security/passwd
   AuthGroupFile   security/group
   AuthName        "Grid Tutorial SVN server"

   # Limit write permission to list of valid users.
   <LimitExcept GET PROPFIND OPTIONS REPORT>
      # Require SSL connection for password protection.
      # SSLRequireSSL

      Require valid-user
   </LimitExcept>
</Location>

To configure SVN authentication for SCDB repository, you need to create one or more accounts in /etc/httpd/security/passwd. You can use htpasswd or openssl passwd -apr1 to generate an encrypted password.

You also need to define SVN ACLs in /etc/httpd/security/svn-repositories-access. A typical file to start is (it assumes the account you created is called quattormgr, if this is a list it must be comma separated):

[groups]
quattor-mgrs = quattormgr

[/]
* = r
@quattor-mgrs = rw

Note: even though it is easily redone, it is better to backup subversion.conf file and files in /etc/httpd/security.

Repository configuration

For Quattor, you need to create a repository with the standard structure inside it (or inside a branch) :

trunk : where you make the changes to your running configuration
tags : used by SCDB administration tool to do deployment
branches : for alternative developments

One of the possible methods to create it with an empty Quattor repository (or repository branch) is (assuming your repository is dedicated to SCDB and its URL is http://svn.example.org/Quattor):

mkdir /tmp/scdb
cd /tmp/scdb
mkdir trunk
mkdir tags
mkdir branches
svn import . http://svn.example.org/svn/quattor --message 'Initial repository layout'

DHCP and TFTPD installation and configuration

DHCP and TFTPD installation

Install DHCPD and TFTPD server from OS distribution. You can do it with the following YUM command:

yum install dhcp tftp-server

DHCP configuraton

If the DHCP server is to be used for Quattor usage only, a basic DHCP configuration (/etc/dhcpd.conf) may be:

# DHCP server configuration

authoritative;
allow bootp;
#allow duplicates;
ddns-update-style none;
#omapi-port 7921;       # Use a non standard port (standard = 7911)

# Edit to reflect your DNS domain name and name servers (a comma-separated list is allowed)
option domain-name "lal.in2p3.fr";
option domain-name-servers nfsserv.lal.in2p3.fr;
option netbios-node-type 2;

# Update to reflect your IP subnet
subnet 134.158.72.0 netmask 255.255.255.254 {

  # Parameters for the installation via PXE using pxelinux
  filename                           "quattor/pxelinux.0";
  #option dhcp-class-identifier       "PXEClient";
  option vendor-encapsulated-options 01:04:00:00:00:00:ff;

  # This is required on RHEL/SL/SLC/CentOS 5.X
  next-server  your.quattor.tftp.server.domain.com;

  # This is now a required line in DHCP configuration.  This
  # option gives the behavior of the previous versions.
  ddns-update-style ad-hoc;

  option routers 134.158.72.1;
}

If you want to share DHCP between Quattor and non Quattor usage, it's probably better to move the last part (subnet...) into a separate file, like /etc/dhcpd/quattor.conf and replace it in the main configuration file by:

include "/etc/dhcpd/quattor.conf";

See man dhcpd and man dhcpd.conf for details about DHCP server configuration, in particular to support multiple subnets and other advanced features.

TFTPD configuration

TFTP server is run by xinetd. In the default configuration provided by the OS installation, it is generally disabled. Enable it by editing /etc/xinetd.d/tftp, modifying disable parameter from yes to no.

Option server_args allows to define the TFTP root directory. By default, it is /tftpboot. If you'd like to use another location you need to update this option and you'll need to define the variable AII_NBP_DIR to reflect that when configuring your site paramaters.

Quattor Deployment Server

Quattor packages required for installing a deployment server can be easily installed by YUM. For this, create the following YUM repository definition on your server:

cat > /root/.quattor/yumroot/quattor.repo <<EOF
[quattor_release]
name=quattor_release
baseurl=http://yum.quattor.org/current
EOF

You will also need access to the EPEL repository, if you do not have a local mirror you can get the RPMs for the latest releases of EPEL from https://fedoraproject.org/wiki/EPEL and install with:

rpm -ivh http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm

After configuring the YUM repositories, you should be able to install the required RPMs with:

yum install aii-pxelinux ncm-ncd ncm-ccm

Note: when you have succeeding installing and configuring Quattor, it is recommended to add a profile for your deployment server so that it will be managed by Quattor! This will help to keep it consistent and up-to-date.

SCDB Initialization

You must have created a repository for Quattor and initialized its structure as explained in section Subversion Server Installation. The http based repository access must be used for quattor, the standalone access won't work (limitation of the build script).

To create your initial SCDB with the standard templates and the associated examples, follow the following steps:

Create a directory that will contain your configuration database (we'll use scdb in this tutorial but can be whatever you want)
In another directory, clone Git repository scdb from GitHub
Go into the directory containing the clone and execute the command below to create your initial configuration database with SCDB tools, the template library and site template examples:
```
utils/scdb/create-vanilla-SCDB.sh -d /path/to/previously/created/scdb/directory
```
Change current directory to your configuration database:
```
cd /path/to/previously/created/scdb/directory
```
Checkout the empty SCDB trunk created during Subversion configuration in your current working directory :
```
svn co http://svn.example.org/svn/quattor/trunk .
```

Configure the repository to ignore some files produced when compiling, using the following command :

cat > /tmp/ignore <<EOF
.settings
build
build.saved
deploy
.project
EOF
svn propset svn:ignore -F /tmp/ignore .
svn ci

Add everything to your repository with command :
```
svn add *
```
Commit your vanilla SDCB with :
```
svn ci -m 'Create initial SCDB'
```

Site Configuration

After copying the SCDB distribution, you need to create your first site. You can do this by copying cfg/sites/example directory and customizing a few templates.

RPM Repositories

In addition to the templates, you also need to mirror the YUM repositories used by the template library. You can find in the example part of the template library (from GitHub repository template-library-examples or from directory cfg/sites/examples/repository created by previous step) URLs of YUM repositories that you can use as upstream repositories to start. You may also want to look at how to use YUM repository snapshots with Quattor.

Note on Apache configuration for RPM repositories: it is recommended to disable the use of index files on these directories with the following options in Apache configuration:

<Directory "/www/htdocs/packages">
    Options Indexes
    DirectoryIndex VeryUnlikelyDirectoryIndex.none
    AllowOverride None
</Directory>

Note2: if you use YUM snapshots that are not under the same path, be sure to add the required Apache configuration to serve them.

Basic System Configuration

Basic system configuration (network parameters, DNS servers, ...) are grouped in template config.tpl and global_variables.tpl in site directory of your site. Look at comments to understand what you need to modify.

Middleware Configuration

Middleware configuration is located in template config.tpl in site/glite directory of your site. Look at comments to understand what you need to modify.

Note: do not be afraid of putting wrong values in your gLite parameters, this can easily be refined later. As a general rule, keep the example values when you don't understand how to change them.

Cluster Configuration

After creating your site, you need to create your first cluster. You can do this by copying clusters/example-3.2 directory (or the cluster example relevant for the gLite version you use), removing all profiles from clusters/example-3.2/profiles and customizing a few templates.

Hardware description

You need to create a template describing the hardware configuration of your machines. This is generally placed in hardware sub-directory of site directory. Look at examples, copy one with a configuration close to yours as a starting point. The name of the hardware template is at your convenience and will be associated with a host name later.

Note: recommendation is to have name of templates describing HW boxes derived from box location rather than its current host name as the same HW may be affected to another host later.

Adding Machine to site/databases.tpl

Before being able to configure the machine, you need to create an entry for the machine name in both variables of databases.tpl. First variable defines the address associated with the machine name, second variable defines the hardware template associated with the machine.

In both variable, the key is the escaped host name. The value is an IP address in the first case, the name of the template (relative to your site name in sites directory) you created in the previous step for the second variable.

Creating Machine Profile

Copy an existing profile in examples corresponding to the machine type you want to create.

Note: as a first node, it is recommended to configure a site BDII as this is the most simple node. When successful with site BDII, the next ones are generally CE and one WN.

Quattor Server Final configuration

Before being able to deploy the created configuration, there is a last configuration step needed to allow deployment of the configuration after successful compilation. This involves :

Adding a hook script to the Subversion repository to trigger the deployment
Adding a script on the Quattor server that will be launched by the hook script, using ssh
Configuring SSH keys to allow execution of the previous script as root (preferably) from the Apache account
Add a CGI script on Quattor server used at end of installation of a machine to allow next boot from local disk.
Configuration of AII

Installation of deployment scripts

SCDB deployment uses a pair of cooperating scripts:

SVN post-commit hook script: this script is launched when ant deploy creates a new deployment tag. This scripts run on the SVN server.
Deployment script: this script is launched by the post-commit hook script to do the real work. It runs on the Quattor deployment server (which may be different from the SVN server).

Both scripts are distributed as part of SCDB, in directory src/hooks. They have to be copied at the appropriate location on the appropriate server:

The hook script, post-commit.py must be copied to the hook directory of the SVN repository (on the SVN server, using example naming /var/svn/quattor/hooks, see SVN server configurion), and given executable permission for Apache user.
The other script, build-tag.py, must be installed (root executable) in /root/quattor/scripts (by default) on the Quattor server.

Both scripts use the same configuration file, /etc/quattor-deploy.conf, see SCDB server-side customizations for details. The configuration file is required (one must exist on each machine if you run SVN server and Quattor deployment server on different machines). If you use a configuration based on suggested defaults and a SVN server and Quattor deployment server co-located on the same machine, a typical configuration file is:

[scdb]
# Update to reflect your configuration
repository_url=http://svn.example.org/svn/quattor

[build-tag]
# If not defined, defaults to parent of this build-tag script directory.
# If not starting with /, relative to parent of this build-tag script directory.
# Ensure the path exists.
svn_cache: /scratch/quattor-deployment/svncache

Note: there used to be a Shell/Perl version of these scripts. These scripts are now obsolete. The configuration file format of the new scripts is different, even though the name may be the same.

build-tag.py also requires file quattor.build.properties to be created in the parent of the directory specified in svn_cache paramater of the above configuration file or its default value (/root/quattor for example provided here). A template of this file is available in SCDB distribution, in src/hooks directory. It must be edited to reflect your local configuration.

Note: you can download the last version of these scripts from QWG repository with the following command:

wget --no-check-certificate "https://svn.lal.in2p3.fr/LCG/QWG/SCDB/trunk/src/hooks/post-commit.py" -O /var/svn/quattor/hooks/post-commit
chmod 755 /var/svn/quattor/hooks/post-commit
wget --no-check-certificate "https://svn.lal.in2p3.fr/LCG/QWG/SCDB/trunk/src/hooks/build-tag.py" -O /root/quattor/scripts/build-tag.py
chmod 755 /root/quattor/scripts/build-tag.py

For more details about these scripts and their customization, see the page on SCDB server-side customizations.

Creation of SSH Keys

Note: this step is necessary only if you use ssh for the communication between the SVN server and the Quattor deployment server. If they run on the same machine, it is recommended to use sudo instead.

When using ssh as the communication method between the SVN server and the Quattor server, it is necessary to configure SSH keys to allow a password-less ssh connection (there is no way to enter a password in the script). To configure these keys, you need to:

Log under the deployment account on the Quattor deployment server and run the command:
```
ssh -b 2048
```
Log in to the Subversion server as the same user as your SVN server (generally Apache account), copy the file with extension .pub generated in the previous step (in the directory ~/.ssh) and try to ssh to the Quattor deployment server using the same account as the one used by the deployment script (typically root).

In case of problems, refer to the troubleshooting section of the SCDB server configuration documentation.

sudo Configuration

Note: this step is necessary only if you use sudo for the communication between the SVN server and the Quattor deployment server. This requires both service to run on the same machine and is the recommended communication method in this situation. If both services run on different machines, you need to use ssh instead.

To configure sudo for SCDB, use the visudo utility and enter the following lines in the sudo configuration (be sure to use the appropriate path and account in your configuration):

Cmnd_Alias   QUATTORDEPLOY=/root/quattor/scripts/build-tag.py *
apache ALL = NOPASSWD: QUATTORDEPLOY
Defaults:apache !requiretty

Note: the last line is required on later versions of RHEL-like operating systems. If it is not given, the sudo will silently fail.

Post-installation CGI Script

At the end of a machine installation, as part of the Kickstart post-intallation script, a CGI script is executed on the Quattor server to change PXE configuration in order for the machine to boot from local disk next time. This allows to set PXE as the first boot device in the BIOS and control re-installation via aii-shellfe command.

This script, aii-installack.cgi, can be found in SCDB directory src/cgis. It must be placed on the Web server running on the Quattor server, in the directory for CGIs.

The apache server must be able to run that script as root. Best is to have sudo installed and use visudo to add the following to /etc/sudoers:

Cmnd_Alias   AIIACKCGI=/usr/sbin/aii-shellfe
apache ALL = NOPASSWD: AIIACKCGI

Configuration of AII

This involves 2 separate steps :

Customization of /etc/aii/aii*.conf files
Customization of AII-related variables in templates

There are 2 AII configuration files that need to be customized to reflect your site configuration:

/etc/aii/aii-shellfe.conf: a typical file is as follows, with paths edited to reflect your configuration.

# URL corresponding to compiled profiles generated by ant deploy
cdburl=http://quattor.web.lal.in2p3.fr/profiles
# use_fqdn must be set to true
use_fqdn=true
# Directory where to write Kickstart configuration files produced by aii-shellfe.
# Must match the directory served by URL defined in template variable QUATTOR_PROFILE_URL.
osinstalldir = /www/htdocs/ks
# Directory where pxelinux.cfg is installed. Default is the recommended locaiton.
nbpdir = /tftpboot/quattor/pxelinux.cfg

/etc/aii/aii-dhcp.conf: check that dhcpconf and restartcmd command match your configuration and edit as necessary. The file referred by dhcpconf must be writable from the AII server. restartcmd may launch a command on a remote machine through appropriate means.

To customize AII configuration files, located in /etc and named aii-*.conf, refer to the comment in each files. Main parameters to customize are in aii-shellfe.conf:

cdburl: URL to use to download profiles
osinstalldir: directory where to place kickstart configuration files produced by AII

Note: if /etc/aii doesn't exist or is empty on your server, copy templates of these files located in /usr/share/doc/aii-x.y.z/eg (with x.y.z matching AII version installed).

There are a few variables to customize in site templates to reflect your Quattor and AII configuration, mainly :

QUATTOR_PROFILE_URL : URL to use to download machine profiles.
AII_OSINSTALL_SRV : Name of the Web server serving OS rpms for the initial install (can be same as main repository server).
AII_KS_SRV : Name of the Web server serving kickstart files. Defaults to AII_OSINSTALL_SRV
AII_ACKSRV : Name of the Web server to use for the post-installation CGI. Defaults to AII_OSINSTALL_SRV
AII_ACKCGI : post-installation CGI URL. Defaults to /cgi-bin/aii-installack.cgi.
AII_NBP_DIR : path of the directory containing the PXE configuration for each machine. Defaults: /tftpboot/quattor/pxelinux.cfg.

These variables are generally defined site-wide, in the template global_variables.tpl located in site directory. Look at provided examples, in SCDB distribution.

Downloading the distribution's images

There are basically 2 methods for dowloading the distribution's images:

Mirror what is already available at another Quattor site, for example http://quattorsrv.lal.in2p3.fr/packages/os (there is one directory per OS version/architecture combination), in a directory served by Apache, for example /var/www/html/packages/os/. You can use wget --mirror to mirror this reference site.
Copy the distribution from a CD or an ISO image into a directory served by Apache , for example /var/www/html/packages/os/. When using an ISO image, it is possible to mount it with mount -o bind and to use it directly in Apache (by mounting under the the directory mentionned before) but this is not recommended as it is often necessary to tweak a little bit the distribution, in particular to properly support gLite compatibity mode.

When the distribution is ready on your RPM server (Apache server), you need to add the boot files used for the PXE installation. They consist in 2 files (vmlinuzand initrd.img) generally located in images/pxeboot directory of the distribution. You need to copy these files in a directory specific to the OS version/architecture located in the same directory as the pxelinux.cfg directory (see variable AII_NBP_DIR configured at the previous step). The directory name must have the usual form with all - replaced by _ (eg. sl530_X86_64).

Compiling and Deploying

After the configuration is finished, you can try to compile your first profile, deploy it and install the machine. This involves the following steps :

In SCDB (working area copy) top level directory :
- Update of RPM repository templates :
```
external/ant/bin/ant update.rep.templates
```
- Profile compilation and deployment (deployment will not occur until compilation succeds) :
```
external/ant/bin/ant deploy
```
On the Quattor server :
- Creation of Kickstart configuration file for the machine :
```
aii-shellfe --configure your.machine.domain
```
- Update of DHCP and PXE for the machine to be installed at next boot :
```
aii-shellfe --install your.machine.domain
```

Note: you can ignore the warning returned by aii-shellfe about base_url is not defined in configuration.

Troubleshooting Initial Installation

In addition to the specific problems mentionned below, you may look at the SCDB FAQ.

Deployment doesn't work

Look at SCDB server-side customizations page.

Last modified 9 years ago Last modified on Jan 14, 2015, 11:26:58 AM

Download in other formats:

Plain Text