Name

UNIX Password, Roles & Node Management: Transfer Details

Transfer Details

The transfer application, password_xfer.pl, is one of the three core scripts in Password Management. It ensures the correct work files are transferred to the correct place on a per-node basis quickly and safely.

Required Arguments

There are no required arguments for password_xfer.pl.

Additional Options

-h: Shows the basic usage of password_xfer.pl.
-d: Turns on debugging.
-v: Turns on verbose output (this makes a lot of noise...).
-n: Don't push, but act like you did.
-N: Don't run the update command, but act like you did. Enabling this pushes the work files out, but does not run password_rcvr.pl.
-P: Preserve ownership for non-core files. This includes files that were included from plugins assigning outgoing file lists. The default is to change the ownership to root:sys.
-t secs: Sets the timeout for connections (default 120).; Note: this option is now worthless; timeout values are now pulled from the pwman.px.timeout.ping, pwman.px.timeout.copy and pwman.px.timeout.plugin properties.
-u user: Sets the user to SSH as (the default is root). You can also use the property pwman.px.ssh.user to set this value.

Plugin Details

password_xfer.pl uses one type of plugin: push. It and it's phases are detailed below.

push: push plugins can be used to prepare a node for new work files, or to verify that the files are there successfully. The pre phase executes before a node has it's work files transferred and updated, and the post phase executes after a node is successfully updated. If for whatever reason password_rcvr.pl exits with a non-zero status the post phase will not be run.

Outgoing Files

By default, a node has pushed to it the following files:

.passwd work file: The generated passwd(4) file. It's prefixed with the nodename, eg node01.domain.com.passwd, and is found in the pwman.work_dir directory.
.shadow work file: The generated shadow(4) file. It's prefixed with the nodename, eg node01.domain.com.shadow, and is found in the pwman.work_dir directory.
.sudoers work file: The generated sudoers file. It's prefixed with the nodename, eg node01.domain.com.sudoers, and is found in the pwman.work_dir directory.
.digest work file: The generated digest file, which contains MD5 checksums of the .passwd, .shadow, and .sudoers files. It's prefixed with the nodename, eg node01.domain.com.digest, and is found in the pwman.work_dir directory.
password_rcvr.pl: The receiver, which ensures the integrity of the work files and their safe update.
password_relocate.pl: The relocator, which relocates ancillary or ``outgoing'' files on the target node.

This list is archived into a tar file, and that tar is extracted on the remote node during update. The password_relocate.pl ensures that all files are put in the right place, which includes the password_rcvr.pl and the work files. Once relocation is done, an update is performed with password_rcvr.pl. If the update is unsuccessfull, any file that was transferred (with the exception of the work files) are attempted to be rolled back.

Plugins can augment the above list by adding files at runtime. These ``outgoing'' files can be copied from anywhere on the filesystem that Password Management is running on, to anywhere via password_relocate.pl. This can include dotfiles from home directories, or per-node inventory information, or system patches, or whatever.

To do this, a push_pre or push_post plugin needs to register a hashref called $outgoing with the following format:

  $outgoing = {
    'local-file-path' => 'remote-file-path',
  };

...where local-file-path is the absolute path to the file that needs to be copied from the Password Management instance, and remote-file-path is the location on the target node where the file should be placed. For example, if you wanted to copy /var/tmp/system.info to the /etc directory on every node, you could simply do this:

  $plugin = sub {
    logThis(3, "stub plugin code which does nothing");
    return 1;
  };
  $outgoing = {
    "/var/tmp/system.info" => "/etc/system.info",
  };

There are limitations, however: outgoing files are evaluated at runtime, so there's no easy way to specify a particular file on a per-node or per-user basis. You can, however, modify the list of outgoing files on a per-node basis during push_pre plugin execution. The hashref is an argument to all push plugins (it's the og_hashref argument), so the following is probably doable:

  $plugin = sub {
    my(%arg) = @_;
    my $og_hashref = $arg{og_hashref};
    my $password_work = $arg{password_file};
    open(WORK, "< $password_work") || die "can't read $password_work: $!";
    while (<WORK>) {
      chomp; 
      my @entry = split(/:/, $_, 7);
      my $cshrc = join('/', ".cshrc");
      if (-d $entry[5] && -f $cshrc) {
        $og_hashref{ $cshrc} = $cshrc;
      }
    } 
    close(WORK);
    $arg{og_hashref} = $og_hashref; ## be sure to re-assign it when you're done
  };

(Try to limit this, however: if you wanted to automatically copy out, say, .cshrc, .login, .vimrc, .profile, .bash_profile, and then you installed 300 real users into that environment, that's 1500 files copied out to N nodes (where N would be every node in that environment). Additionally, many of these files have the ability to include additional files; users might be surprised to find that only one-half of their bash settings made it.)

Files that are copied out keep the same permissions and ownership found on the local system.

Transferring via SSH to local nodes

password_xfer.pl uses SSH as a transport and authentication mechanisim to transfer new work and ancilliary files out to target nodes. Outgoing tarballs are transferred by essentially outputting the tarball to the STDIN of a remote command issuing cat - filename> via cmd(). Other commands are run as-is. Client authentication is done via SSH identity keys.

password_xfer.pl should be compatable with both SSH protocol 1 and protocol 2 servers (really, it's dependant on how you built Net::SSH::Perl; there's no protocol-dependant code in password_xfer.pl); the rule of least common denomenator was followed here. The oldest revision of SSH that this was tested with is SSH version 1.2.26, protocol 1. The most recent is OpenSSH 3.7.1_p3.

Transferring via R to remote nodes

If a node is marked for remote operation (via the +REMOTE tag), then Password Management tries to transfer the NCF and work files to that remote Password Management instance via the R API. R uses HTTP as a transport, so you can encrypt all the traffic however you want with SSL, you can authenticate with any Auth mechanism supported by LWP::UserAgent, and best of all: you can proxy connections across multiple subnets and through router ACLs, allowing you to manage physically and topologically diverse nodes in the same way.

You'll want to review the documentation on the R API for more information.

Note that nodes that are pushed via R remote are treated like local nodes from the perspective of the remote Password Management instance. If you make changes to push plugins (like the order in which they're executed, or by adding or removing plugins) then you must also do this on the remote Password Management instance. There is currently no method for synchronizing this automatically.

Not transferring to a node

You might find yourself in the position where you have a node managed by Password Management but you don't want to push to it - the node may be down for extended maintenance, or you may not want to push any user or password data but still want to keep it in active inventory, or it may be an unsupported or unpushable device (like a layer 2 switch, a hardware load balancer, or a firewall). To accomplish this, a special node tag exists that you can set in the node's NCF: +NOPUSH. The value of this tag should be a URL that details why it's not pushed via Password Management, and perhaps how it's credentials might be changed. Example:

  +NOPUSH=http://local-docs-server.corp.domain.com/node01.domain.com.html

Author

Jon Gilbert <jong@jong.org>

Version

$Id: pwman_docs_transfer.pod,v 1.2 2005/10/20 08:46:34 jgilbertsjc Exp $