2. The sysf Command Syntax

The general syntax for sysf is as follow:

    sysf [PARAMETERS] [COMMAND] [HOSTS] [ENTRY_NAMES]

In the following, the parameters and command names are listed as -PARAMETER=X where PARAMETER is the parameter name and X is its short cut. So sysf -PARAMETER ... is equivalent to sysf -X ....

The PARAMETERS control certain aspect of sysf. The COMMAND specifies the action to be taken; one and only one command has to be specified. The HOSTS list specifies the host or the list of hosts on which the command must be executed. The ENTRY_NAMES list specifies the list of entries (entry names) for which the command must be executed.

2.1 PARAMETERS

The valid parameters are:

• -mailto=m2 EMAIL_ADDRESS: email the output to the specified address.
• -echo=e : echo the host-names and entry names as they are being treated.
• -echo_host=eh : echo the host-names.
• -by_system_file=bsf : the arguments of sysf are taken as the full path name of the system file instead of entry names. This is useful to find out the entry name or the config file of a given system file. The command sysf -bsf SYSTEM_FILE will display the information.
• -rsh : use rsh for remote access (see also the sysf.cf file).
• -ssh : use ssh for remote access (see also the sysf.cf file).
• -config_dir=cd CONFIG_DIR : set the config directory path (see also the sysf.cf file). This is useful to make some tests.
• -config_file=cd CONFIG_FILE : change the name of configuration file, [sysf.conf]. (see also the sysf.cf file).
• -keep_dead_hosts=kdh : do not remove the hosts from the DEAD host group.
• -forgiving : does not abort when some errors occurs: allow rsh or ssh path not to exist.
• -exclude_entry_names=xen ENTRY_NAMES : remove the ENTRY_NAME from the argument list where the ENTRY_NAME is a coma separated lists of entry names and config groups. This is useful to exclude a few entry names from a config group or some config groups from the full list of entry names (ALL).

2.2 COMMAND

The sysf commands all have a verbose name (like install) and a short abbreviation (like I) . Every command that actually modifies the system or the config files have an upper case abbreviation. Most other commands have a lower case abbreviation but some have an upper case one. Both the command name and the abbreviation must be preceded by the character - .

• install

      sysf -install ENTRY_NAME
      sysf -I ENTRY_NAME
  

  Install the configuration file. The config file overwrites the system file. The file attributes are copied too. If the config file is a symbolic link to NONE, the system file is removed.
• first_install

      sysf -first_install ENTRY_NAME
      sysf -FI ENTRY_NAME
  

  Does the same as -install except that before the system file is overwritten by the config file, sysf makes a backup copy of the system file in the same directory using the same name but with the .DIST extension added to it. The backup copy is created only if it does not exist making sure the distribution version of the file is always available. The file attributes are copied too. The .DIST files is not created if the flags r or d (directory) are set for that entry in the file sysf.conf. The r flag would typically be set for the script files in /etc/crontab.daily where one does not want spurious files. If the config file is a symbolic link to NONE, the system file is removed.
• OS_install

      sysf -OS_install ENTRY_NAME
      sysf -OSI ENTRY_NAME
  

  This command is intended to perform the initialisation of a new host. All SHARED files are ignored. If the config file exists the system file is installed using the sysf command first_install. If the config file does not exist nothing is done unless the sysf entry has the h flag set in the file sysf.conf. In that case the config file is created using the sysf command new. The file attributes are copied too. If the config file is a symbolic link to NONE, the system file is removed.
• archive

      sysf -archive ENTRY_NAME
      sysf -A ENTRY_NAME
  

  Archive the system file. The configuration file is overwritten by the system file. If the configuration does not exist, if it is a host group, a DEFAULT file or a SHARRED file an error message is displayed. One has to use the -new, -makedef or -makeshared flag instead. The file attributes are copied too.
• new

      sysf -new ENTRY_NAME
      sysf -N ENTRY_NAME
  

  Create a new configuration file (CONFIG.HOST) for the specified CONFIG name. This is used when there is no config file or when one wants to use a host specific file, rather than a host group or DEFAULT one for this config entry. The archive command must be used to update the host specific config file once it exists. The file attributes are copied too. If the system file does not exist, the config file becomes a symbolic link to NONE.
• makedef

      sysf -makedef ENTRY_NAME
      sysf -MD ENTRY_NAME
  

  Create or update the default config file (CONFIG.DEFAULT) for the specified entry name. This copies the system file to the DEFAULT config file. After doing this one should update the system files on all the hosts that use the DEFAULT config file. The file attributes are copied too. If the system file does not exist, the config file becomes a symbolic link to NONE.

  Notice that if a host config file or any other host group file exist for the current host, it is not removed. One must do it by hand if it is required.

• makeshared

      sysf -makeshared ENTRY_NAME
      sysf -MS ENTRY_NAME
  

  Create or update the shared config file (CONFIG.SHARED) for the specified entry name. This copies the system file into the SHARED config file. There is no further update required as the file is shared by all computers. The file attributes are copied too.

  Notice that if a host config file or any other host group file exist for the current host, it is not removed. One must do it by hand if it is required.

• makegroup

      sysf -makegroup HOST_GROUP ENTRY_NAME
      sysf -MG HOST_GROUP ENTRY_NAME
  

  Create or update the default config file for the specified host group (CONFIG.HOST_GROUP) for the specified entry name. This copies the system file into the HOST_GROUP config file. After doing this one should update the system files on all the hosts belonging to that host group. The file attributes are copied too. If the system file does not exist, the config file becomes a symbolic link to NONE.

  If the HOST_GROUP is not defined in the hosts.conf file, sysf displays an error message and stops. The current host does not have to belong to the specified host group, even though you would expect it to in most cases.

  Notice that if a host config file exists for the current host, it is not removed. One must do it by hand if it is required.

• uninstall

      sysf -uninstall ENTRY_NAME
      sysf -U ENTRY_NAME
  

  Execute the BIN/ENTRY_NAME auxiliary command with the -Remove flag but only for entries for which the U flag is set in the sysf.conf file. When the U flag is not set or for directory lists (when the flag g is set), the auxiliary command is not executed and sysf does nothing at all. Typically this will remove auxiliary files or symbolic links as in the rc directory. sysf does not do anything itself.
• info

      sysf -info ENTRY_NAME
      sysf -i ENTRY_NAME
  

  Display some information about the entry name including the last modification date, the size and full path-name of both the config file and the system file. It also tells if the config file and the system file are identical and which one of the two was modified last.
• check

      sysf -check ENTRY_NAME
      sysf -c ENTRY_NAME
  

  Checks that the config file and the system file are identical. Nothing is displayed unless the two files differ. This is typically used to check groups of config files and email the result using the mailto parameter. The file mode, uid and gid are also compared.

  If the config file is a symbolic link to NONE and the system file exist, a discrepancy message is produced. If the system file does not exist, a warning message is produced unless the config file is a symbolic link to NONE.

  One should use the check command from time to time to ensure that none of the system files have been changed the without updating the corresponding config file. The diff command can be used to check how the config and system files differ.

• is_not_conf

      sysf -is_not_conf ENTRY_NAME
      sysf -nc ENTRY_NAME
  

  Lists the sysf entries with either no system or no config files. This command is used to check the consistency of the entries defined in the sysf.conf file. If the config file is a symbolic link to NONE and the system file does not exist the entry is not listed.
• diff

      sysf -diff ENTRY_NAME
      sysf -d ENTRY_NAME
  

  Lists the differences between the system file and the config file using the unix diff command. If after checking the consistency between the config files and the system files it appears that there are differences, one can use this command to list the differences. Notice that this lists only the difference of contend between the two files. To check the ownership and access modes, one must use the check command instead.
• diff_host

      sysf -diff_host HOST -h HOST2 ENTRY_NAME 
      sysf -dh HOST -h HOST2 ENTRY_NAME
  

  List the differences between the config files for HOST and HOST2 using the diff command. The sysf entries with the flag s set are ignored and produce no output. If a config file does not exist for neither hosts, then this is displayed only if echo is on. This sysf command is used to list the differences between two hosts. Notice that, unlike the -check_host command, the entries with the h flag set can be compared. While -check_host is used to list the files that differ between two hosts, this command is used to check what the differences actually are.
• check_host

      sysf -check_host HOST -h HOST2 ENTRY_NAME 
      sysf -ch HOST -h HOST2 ENTRY_NAME
  

  List the config files which differ between HOST and HOST2. The sysf entries with the flag h and s set are ignored and produce no output. If a config file does not exist for neither hosts, then this is displayed only if echo is on. This sysf command is used to list the differences between two hosts, setting aside the files that are shared (s flag) or specifically host dependent (h flag). Notice that it is the config files that are compared, not the system files.
• install_mode; install_uid; install_gid

      sysf -install_mode -install_uid -install_gid ENTRY_NAME
      sysf -Im -Iu -Ig ENTRY_NAME
  

  Change the file mode, uid or gid of the system file to the corresponding value of the config file. Nothing else is changed. These 3 install commands are the only commands, together with the corresponding archive commands, that can be executed simultaneously.
• archive_mode; archive_uid; archive_gid

      sysf -archive_mode -archive_uid -archive_gid ENTRY_NAME
      sysf -Am -Au -Ag ENTRY_NAME
  

  Change the file mode, uid or gid of the config file to the corresponding value of the system file. These 3 archive commands are the only commands, together with the corresponding install commands, that can be executed simultaneously.
• cat

      sysf -cat ENTRY_NAME
      sysf -C ENTRY_NAME
  

  Displays the config file on the screen using the cat command.
• catsys

      sysf -catsys ENTRY_NAME
      sysf -Cs ENTRY_NAME
  

  Displays the system file on the screen using the cat command.
• list_groups

      sysf -list_groups
      sysf -lg
  

  List all the config groups.
• list_configs

      sysf -list_configs
      sysf -lc
  

  Lists all the config files by config groups.
• list_1group

      sysf -list_1group GROUP
      sysf -l1g GROUP
  

  Display all the entry names belonging to that config group.
• find_group

      sysf -find_group ENTRY_NAME
      sysf -fg ENTRY_NAME
  

  List the config group to which each entry name belongs.
• list_hosts

      sysf -list_hosts
      sysf -lh
  

  Lists the host groups with their members.
• list_hosts_group

      sysf -list_hosts_group HOST_GROUP
      sysf -lhg HOST_GROUP
  

  Lists all the hosts belonging to that group. The list can be used inside a shell foreach loop to scan a list of hosts:

      foreach host (`sysf -lhg ALL`)
       echo $host
       rsh $host "df -k"
      end
  

• list_these_hosts_group

      sysf -list_these_hosts_group -h HOSTS
      sysf -lthg -h HOSTS
  

  List the host groups to which each host belongs.
• list_arg_hosts

      sysf -list_arg_hosts
      sysf -lah
  

  Lists the argument hosts, that is the hosts list excluding the DEAD hosts and the hosts excluded by the exclude_hosts list. This differ from the -list_host_group command which outputs the group list as defined in the hosts.conf file and does not exclude the DEAD hosts. When using sysf to scan a list of hosts, one would thus use -list_arg_hosts rather than -list_host_group. Here is an example:

      foreach h (`sysf -lah ALL -xh cox`)
        echo $h
        rsh $h uname -a
      end
  

• list_arg_entry_names

      sysf -list_arg_entry_names
      sysf -laen
  

  Lists the argument entry names instead of performing a command. This is the full list of entry names made from all the entry names and expended config group from the argument list, less the exclude_entry_names expended list of entry names. In other words this the detailed list of entry names on which the sysf command would normally be executed.

  This is useful to test that a given combination of entry names and exclude list contains the correct entries.

• belongs_to

      sysf -belongs_to HOST_GROUP
      sysf -bt HOST_GROUP
  

  Check that the argument hosts all belong to the given HOST_GROUP and display yes if they do and no otherwise. This is useful in script files to test if a given host belongs to a griven host group as shown in the following c-shell example:

      if (`sysf -bt LINUX -h "$1"` == "yes") then
        echo "host $1 belongs to the host group LINUX"
      else
        echo "host $1 does not belong to the host group LINUX"
      endif
  

2.3 HOSTS

The host on which the sysf command is executed is the default host. One can otherwise specify a host or a group of hosts on which to execute the command. The valid argument to build the hosts list are:

• -hosts=h HOST_LIST
• -exclude_hosts=xh HOST_LIST

The HOST_LIST must be the name of a host or a coma separated list of hosts (with no spaces at all). One can also use and mix names of host groups, which are defined in the sysf.hosts file, and which stands for all the hosts listed in these groups.

The actual list is built as follow: every name on the -hosts value is taken as a host-name to add to the list unless it is the name of a host group which is then expanded as the list of all the host belonging to that group. The hosts name are made into a single list from which multiple entries are reduced to a single occurrence (the first one). Then the -exclude_hosts is parsed in the same way except that these hosts are removed from the first list. By default the -hosts argument is the current host while -exclude_hosts always contain the DEAD host group.

Hosts groups are defined in the sysf.hosts file in the config directory. Group names must start with an upper case letter while hosts names must always start with a lower case letter. The host group ALL should refer to all the known hosts. The host group DEAD is interpreted a list of hosts that are currently not working and that must be removed from any list of hosts, preventing sysf to wait for the remote connection to time out.

Assuming that the hosts.conf file is as follow

DEAD = gates;
WEB_SERVER = stallman pike;
LINUX = trovald cox stallman;
UNIX = kernigan ritchie pike;
DEPRECATED = gates guillotine chastity_belt;
ALL =  LINUX UNIX DEPRECATED;

    # sysf -lha -h ritchie
    ritchie
    # sysf -lha -h kernighan,ritchie
    kernighan ritchie
    # sysf -lha -h LINUX
    trovald cox stallman
    # sysf -lha -h ritchie,UNIX
    ritchie kernigan pike
    # sysf -lha -h ritchie,DEPRECATED -xh chastity_belt 
    ritchie guillotine
    # sysf -lha -h ALL -xh cox,WEB_SERVER,guillotine
    trovald kernigan ritchie chastity_belt
    # sysf -lha -h ALL -xh LINUX,WEB_SERVER
    kernigan ritchie guillotine chastity_belt
    # sysf -lha ALL
    trovald cox stallman kernigan ritchie pike guillotine chastity_belt
    # sysf -lhg ALL
    trovald cox stallman kernigan ritchie pike gates guillotine chastity_belt

2.4 ENTRY_NAMES

The sysf entries are listed in the sysf.conf file in the config directory and the entry names is the name in the first column. When no entry name is specified as a sysf argument an error message is displayed if the command being executed modifies a system or a config file (install, new , makedef, makeshared, makegroup, uninstall, first_install, OS_install,archive, install_mode, install_uid, install_gid, archive_mode, archive_uid, archive_gid). For the other, harmless, commands, it defaults to the name ALL which corresponds to all the config files. The entry names can also be the names of config groups (the second column in sysf.conf). In that case the name is replaced by the list of all the entries belonging to that config groups.

To determine the config file of a given host, sysf searches first for the file with the host-name extension. If there isn't one, sysf scans all the host groups to which the host belongs (in the same order as they appear in the hosts.conf file) and takes the first file found with the matching suffix. If this fails, the CONFIG_NAME.DEFAULT file is used, and if there isn't any, a warning message is displayed. The suffix SHARED is used for the sysf entries which have the s flag set. This is for files that are stored on a shared (NFS mounted) file system.

Assuming that the sysf.conf file is as follow

clock        =  etc     /etc/sysconfig/clock    clock;
inittab      =  etc     /etc/inittab            inittab;
lilo.conf    =  etc     /etc/lilo.conf          lilo.conf       h;
exports      =  filesys /etc/exports            exports         h;
fstab        =  filesys /etc/fstab              fstab           h;
smb.conf     =  filesys /etc/samba/smb.conf     smb.conf        h;

Here are some example:

• sysf -check fstab :

  Check the fstab file.

• sysf -check clock smb.conf :

  Check the fstab and smb.conf files.

• sysf -check etc :

  Check the etc group. that is the files clock, inittab and lilo.conf.

• sysf -check ALL :

  Check that all the config files are up to date and list those that are not.