usasetup - bootstrap the Unix::Sysadmin framework




usasetup bootstraps the Unix::Sysadmin framework for your environment. The script scans your system, asks a series of questions, and saves the answers. Running usasetup is one of a series of steps you need to take in order to fully configure Unix::Sysadmin. The entire procedure is documented in the Unix::Sysadmin::Setup manpage. An overview of the framework is available in the Unix::Sysadmin manpage.

Data Entry

Bootstrap Phases

usasetup runs in two phases. The first phase runs without benefit of any support from the Unix::Sysadmin framework itself. It asks for basic information and stores the answers in the Perl source files of the framework. Once this is done a second phase is run that uses the framework to complete the bootstrap procedure. The following sections detail these phases.

First-stage Bootstrap

Phase one of the script first checks to ensure that the user running the script has root privilege. If so, usasetup asks where your configuration files will be stored and if you want to use a ``canonical master'' host. (See The Canonical Master for an explanation of what a ``canonical master'' is for.) If you answer ``yes'' to this question, usasetup asks you for the name of this host. The program stores the answers you give in the module file. This file is located in your perl site_lib directory under Unix/Sysadmin. If this file already has answers entered for the questions asked by usasetup, the script will use these as defaults for its prompts.

Second-stage Bootstrap

With this basic information entered into the Unix::Sysadmin framework, usasetup enters into phase two of the bootstrap. This is implemented in a second script called usasetup2.

Configuration Directories

usasetup2 first checks for the existence of the configuration directory your entered in phase 1. If it does not exist, the script offers to create it for you. If it does exist, the script checks the permissions on the directory and its subdirectories. These should be 0700, or read,write,execute for the owner (root) only. The permissions are restrictive because the framework will be storing hashed passwords under these directories. usasetup2 then offers to scan the etc directory under the configuration base directory to check the modes of any files that may be stored there. If this is the first time you have installed the framework, no files will have been saved in your etc directory yet. If you are upgrading or re-running usasetup, you may have data files from a previous installation in your etc directory that you want to save. If so, it's a good idea to let usasetup2 scan these files to make sure they have restrictive permissions set. If you let it, the script will set the mode of any non-directory file it finds in your etc directory to 0600, or read,write to owner (root) only.


Unix::Sysadmin stores information about the host the framework is installed on in a special Host record kept under your framework etc directory in a file called this_host. The format of this file is identical to records in the Host.list file. (see the Unix::Sysadmin::Host.list manpage.) The usasetup2 script now attempts to initialize this file. If a this_host file already exists, usasetup2 asks if you want to keep it as it is with no changes. If you say ``no'' to this question, usasetup2 asks if you would like to use the values stored there as default answers for the questions that follow. If you have not chosen to keep a preexisting this_host file without changes, usasetup2 asks for the host's name, the OS the host is running and for the location of the management SSH key. The first two questions will take their defaults either from a preexisting file, or from probed values. The OS is a colon seperated list: NAME:MAJ:MIN:TEENY, where NAME is the OS name, MAJ is the major version number, MIN is the minor version number and TEENY is the really minor version number. For example:


Is correct for a system running Linux 2.2.14-5. The last question has no default value. You must enter the complete path to the SSH key used to grant access to the Unix::Sysadmin clients. For example, '/root/.ssh/access' would be a common choice on Linux or BSD, while '/.ssh/access' would be more common on Solaris.

The Canonical Master

In the first stage of the bootstrap, you were asked to name a canonical master host. This host keeps the canonical copies of the standard Unix password, group and automount database files. At this point usasetup2 attempts to set up the framework's picture of this host. The script starts by checking the manageability of the named canonical master host. It first tries to ``ping'' the host. If that succeeds, it attempts to telnet to port 22 on the master, where the secure shell daemon normally waits for connections. If the SSH daemon answers, the script then tries to run a command on the master as root, using the SSH key specified earlier. If that succeeds, the script probes the master for OS version information. Finally usasetup2 searches for a preexisting Unix::Sysadmin host database. If it finds one, it searches for the master host in that database. If the master is found, the script updates its record with the information collected by the previous probe. If the master is not found, usasetup2 creates a record for the master, creating and initializing a host database if necessary.

Database Setup

In the next step, usasetup2 offers to initialize or update your Unix::Sysadmin databases for users, groups and automount entries. For each database in turn, usasetup checks for an already existing file. If such a file exists, the script gives you the choice of initializing a new database from the master, merging data from the master into your existing database, or leaving your existing database intact without changes.

Client Machine Setup

Next usasetup2 offers to add or update your database of the machines that will be managed by the Unix::Sysadmin framework. If you already have a Host list database, the script offers you the choice of keeping your current file unchanged adding hosts to your existing file or replacing the file with a new host list. If you choose either of the last two options, or if you had no preexisting host file, the script gives you you a choice of four ways to providing a list of host names to add to the list.

input from command line
The script will enter a loop in which you can enter host names one at a time from the command line. Press return without entering anything to terminate the loop.

edit a file
The script will use the editor specified in your VISUAL env variable, your EDITOR env variable if VISUAL is not defined, or vi if neither is defined, to edit a temp file into which you can type the names of your client hosts, one per line.

specify a file
The script will ask for the name of a file containing host names, one per line.

specify a file in /etc/hosts format
The script will ask for the name of a file in /etc/hosts format from which to extract the names of the client hosts.

You are also given the choice of skipping the client set up. If you don't select this option, the script loops through the given host names, subjecting each to the same treatment given to the canonical master above. That is, each host is probed to ensure that it is set up for access by Unix::Sysadmin and its OS, shadow password and automounter configuration is probed. Then the script searches for a preexisting entry for the host in the list. If one is found, it is updated with the probed values. If no host entry is found, a new one is created and added to the list. After processing all the given host names, usasetup saves the new or modified host list.


Man(%%3) pages (programmer's docs):

the Unix::Sysadmin::Host manpage, the Unix::Sysadmin::User manpage, the Unix::Sysadmin::Automount manpage, the Unix::Sysadmin::Group manpage, the Unix::Sysadmin::Netgroup manpage, the Unix::Sysadmin::List manpage, the Unix::Sysadmin::Cmds manpage, the Unix::Sysadmin::Files manpage the Unix::Sysadmin::Utility manpage the Unix::Sysadmin::Config manpage, the Unix::Sysadmin::Scoped manpage

Man(%%5) pages (file formats):

the Unix::Sysadmin::Host.list manpage, the Unix::Sysadmin::User.list manpage, the Unix::Sysadmin::Automount.list manpage, the Unix::Sysadmin::Group.list manpage, the Unix::Sysadmin::Netgroup.list manpage

Man(%%8) pages (manager's docs):

the Unix::Sysadmin manpage, the Unix::Sysadmin::Setup manpage the usasetup manpage

the usatest manpage

the usabackup manpage

the usaupdate manpage

the usapush manpage


Howard Owen <> =cut