Login

Etch QuickStart Guide

Introduction

This guide is intended to help you get a production grade etch installation configured so that you may evaluate and use etch in your environment on one or more hosts. If you'd like to set up a somewhat quicker demo on a single host see this page.

Selecting a Transport Mechanism

The configuration repository is a directory tree of configuration files for etch. Your etch clients need some way to retrieve their configuration repository from your etch server(s). The recommended mechanism is to use rsync over ssh, but other options are possible, including fetching a tarball of the repository via https or sftp, or using CVS over ssh. Consider your environment and the file transfer mechanisms you might already be using and decide which one will provide the optimum balance of security, speed, minimal use of resources (network bandwidth, server horsepower, etc.), and familiarity for yourself and other admins.

Configuring the Server

This guide will assume you are following our recommendation and using rsync over ssh as your transport mechanism. For sake of example we will assume your server is called etch.example.com and you will be using a user named 'tools' to run the rsync service, and the 'tools' user's home directory is /home/tools. Given the restrictions on the SSH key used it would be fairly harmless to run the service as root if don't wish to create a new user. Just use the path to root's home directory for the ssh keys, and /etc/rsyncd.conf instead of putting an rsyncd.conf in the user's home directory.

1. Generate an ssh key pair with ssh-keygen. If you aren't familiar with using ssh-keygen then ssh-keygen -t dsa is a good way to generate a key for etch. Enter /home/tools/.ssh/etch as the place to store the generated key, do not enter a passphrase. Copy the public key /home/tools/.ssh/etch.pub into the 'tools' user's authorized_keys file, /home/tools/.ssh/authorized_keys with the following restrictions added in front of the key. Changing the comment at the end of the public key from something like 'tools@etch.example.com' to 'etch' might help you keep track of the key better.

   command="rsync --server --daemon .",no-port-forwarding,no-X11-forwarding,
   	no-agent-forwarding,no-pty ssh-dss AAAA...
   

2. Create /home/tools/rsyncd.conf as follows. The last line assumes you are storing your etch configuration repository in CVS. If you are using a different revision control tool and it leaves similar signs of its presence littered in your repository you might filter them out.

   [etch]
   comment = Source of etch configuration files
   path = /home/tools/etch/configs
   # Can't chroot as a non-root user
   use chroot = false
   exclude = CVS/
   

3. Download the etch distribution from the download page. Unpack it in /home/tools and either move or symlink etch-version to etch. That sets up /home/tools/etch/configs as referenced in the rsyncd.conf above. The other directories in the distribution will be explained later. Your configuration goes into the etch/configs/source/ directory. See the demo page for a few sample config files to start with, or the manual for complete instructions on building your configuration in etch.

And of course you'll eventually want to create an etch group named something like 'etch_server' that configures all of this for you. :)

Network-Aware Package Management Tools

At this point we'd like to make an aside and recommend that you deploy a network-aware package management tool, particularly one that will chase dependancies, if you haven't already. This will make deploying etch easier, and you will find that it makes using etch to manage your systems easier as well. For RPM-based systems such tools include yum, apt-rpm, and up2date/RHN. Yum is our recommendation. It is standard on the Fedora releases and easily deployed on Red Hat Enterprise Linux. FreeBSD's package management tools include some rudimentary network and dependancy chasing support, see the -r flag in the pkg_add man page. Blastwave's pkg-get is our recommendation for Solaris.

Both the FreeBSD and Solaris tools support only one package repository. All of the RPM tools allow you to point the tool at multiple repositories and the tool will pull from any of them as necessary. (Creating your own "channels" with up2date/RHN requires the use of either a RHN Proxy Server or a RHN Satellite Server.) For example, a typical yum configuration would have a repository called 'base' for the original RPMs supplied by Red Hat, a repository called 'updates' for the updated RPMs that Red Hat has released, and a site-specific repository of RPMs for things like etch. When you use yum to install etch it would pull the etch RPM from the site-specific repository, but would pull the RPMs for the CPAN modules from the base/updates repositories. That is all done transparently for you, yum looks at the dependancy list in the etch RPM and tries to satisfy those dependancies from any of its available repositories.

In the absence of multiple repository support in the FreeBSD and Solaris tools your best bet is to maintain your own repository with a mix of your own packages and packages supplied by others. You can maintain some semblance of order by maintaining the various package sets in different directories and then symlinking everything into a common directory that you point your packaging tool at. The FreeBSD packaging tools are already set up for this to some extent, as they expect the final directory in the path they are pointed to to be a directory named 'All'. So you could have a directory structure that looks like the following, with the All directory containing symlinks to the packages in the base and mysite repositories:

/pkgs/freebsd/4/i386/base/
/pkgs/freebsd/4/i386/mysite/
/pkgs/freebsd/4/i386/All/

Perl on the Clients

Please see this page for instructions on preparing Perl on your client systems for etch. There are some relationships between the instructions on that page and the instructions in the next section on building your client package, so you may want to read both before starting work on either.

Building the Client Package

Prepare

If you followed the directions above and unpacked the etch distribution as /home/tools/etch you will have a /home/tools/etch/client directory. First up you'll need to update some scripts and keys to match your environment:

• Update etch/client/var/etch/ssh/etch with the private SSH key in /home/tools/.ssh/etch generated above in the Configuring the Server section.
• Update the SERVER variable in etch/client/var/etch/fetch_configs based on the user and server you are using in your environment.
• Add the SSH host keys for your etch server(s) to etch/client/var/etch/ssh/known_hosts. To grab all possible key types at once:

      ssh-keyscan -t rsa1,rsa,dsa etch.example.com >>
  	    etch/client/var/etch/ssh/known_hosts
      

In a few cases you'll also need to adjust some packaging files for your environment:

• Red Hat: Make sure you have the rpm-build RPM installed. By default the rpmbuild program will write out packages in /usr/src/redhat, which requires that you run it as root. If you'd prefer to run the make as yourself (recommended), create $HOME/.rpmmacros:

      %_topdir /home/you/rpm
      

  Then mkdir -p $HOME/rpm/RPMS  Packages will now build in $HOME/rpm
• Solaris: If using Blastwave packages copy depend.CSWperl to depend. If using Sunfreeware copy depend.SMCperl to depend and read the notes in that file.
• FreeBSD: Update the version numbers of perl and the other packages in the packlist file to match the exact versions in your repository. Update the srcdir setting with the path to your working copy.

Build

Check the Makefile for the make target for the package you want to build. Run make. FreeBSD and Solaris packages will be generated in the current directory. As mentioned above Red Hat packages will either be generated in /usr/src/redhat or $HOME/rpm depending on your config.

Deploy and Run

At this point you should be set to install the appropriate etch package and any dependancies on your client system(s). If you have a package tool that chases dependancies this should be fairly painless.

Once the package is installed try to run /var/etch/fetch_configs. If that is successful you should have a /var/etch/configs/ directory that was copied from your server. Now try to run /var/etch/configs/etch without any options, it should print out a help message.

Congratulations, you're ready to run etch. See the manual for more information on building up your etch configuration repository. Be sure to check out the source-samples directory within the distribution, it contains an extensive selection of sample configurations.