UNIX Password, Roles & Node Management: Basic Installation

Basic Installation

Control Node Selection

You'll need a host (or node) to run a Password Management instance on. This will be your ``control node''. It should be a node with limited user access. It should also be on a fairly secure subnet (it's probably not a good idea to have it accessable by the general Internet). It should also be able to query or access whatever authorative user database is currently existing (for example, if your authorative source is NIS, then it should be part of that NIS domain).


Ensure you have all of the following installed. Installing and setting these up will differ wildly depending on your OS vendor and your personal preferences, so I won't try to tell you how to get them installed. For the most part, perl -MCPAN -e install Module::Name should work just fine.

Getting the package

Download the most recent release .tgz from the SourceForge pwman-covad project:

Save it to a temporary directory somewhere on the target control node.

Setting up a data directory

You'll need to create a data directory structure to put all your control files, your logs, and so on, into. It should be seperate from the installation prefix, to make upgrades easier. In our example, we'll use


Create this directory, and set its permissions to 0755 (u+rwx,a+rx).

Using revision control for your data

It's a very good idea to keep the files in your data directory under control of some sort of revision system. RCS is an excellent method, as it requires very little work to set up and is installed on just about every UNIX system. CVS is also a good choice, but requires a little more thought and planning. If you're just wanting to get this spun up quickly, don't worry about this; you can turn on revision systems later.

(If you don't have much experience with revision systems, I highly recommend that you start, and soon - your life will be much simpler. Check out ``Applying RCS and SCCS'' for a quick no-brainer overview, or reference the rcs and cvs manpages.)


Extract the tarball you already downloaded, and chdir into the password_management directory:

  # gunzip -c password_management.tar.gz | tar -xvf -
  # cd password_management

Run the installer. You'll need to specify two arguments: PREFIX and DATA_DIRECTORY

  # perl ./ PREFIX=/opt/password_management DATA_DIRECTORY=/opt/pwman_data

The installer will check your prereqs, and copy the required files to the PREFIX directory (if the directory doesn't exist, it'll of course try to create it). The scripts will be modified to ensure that the same build of perl5 is used for all of them, and that the correct library path is inserted. The installer will also modify the default properties values for you.

If you keep your perl5 libs and modules in a non-standard location, you may have to extend your @INC with the PERL5LIB environment variable.

If you're curious, or if you want to debug what might be a problem, you can set the environment variable DEBUG to a non-zero value, and the installer will output slightly more information.


You're now ready to configure the basic stuffs that Password Management needs to operate.


Move to the newly installed Password Management instance, and go into the ./etc directory

  cd /opt/password_management/etc

In this directory is a file called This file contains a number of operator-modifyable settings that you can tweak to your hearts delight. They've all got some level of explanation as to what they do. At this stage, you really only need to worry about the following:

Note that Password Management's Covad::Pwman::Properties module is smart enough to re-execute a script when it detects that any of the above three environment variables need to be re-set based on the properties file.


You need to choose how you want to turn login names into users. This is done by querying an authorative source for user data. This source can be NIS or NIS+, or it can be an ActiveDirectory instance with SFU installed, or whatever you have.

``Obtainment'' is a phase of the, and it happens before generation. It works a little like stackable PAM modules: for each username found, query each obtainment source in turn. If the user is found and a valid account exists, then go on to the next username (you can slightly modify this behavior with the property

Password Management comes with at least three obtainment plugins. They are located in the $PREFIX/plugins directory, and are:

You can have any number of obtain_pre_ plugins. You might have to consolidate many different authentication sources - perhaps of different formats or systems - into one cohesive user build process. Or maybe you've got an easy installation, and you've only got the one authentication source. Regardless, you can only ever have one obtain_post_ plugin. (For now, let's assume you're running NIS and that the obtain_post_NIS_covad plugin works for you.) Move the obtain_post_debugging plugin aside to .obtain_post_debugging for now.

  # cd /opt/password_management/plugins
  # mv obtain_post_debugging .obtain_post_debugging

Now your obtainment plugins should be:

This is the order in which they will be processed; hacks entries will be expanded first, and then if the user isn't found, NIS will be queried.


You'll need to set up your environment listing. This will require some thought, because it's not the easiest thing to change once you start to add nodes and roles.

(Check out the ``Nomenclature'' document; it'll show you some examples on how you can break down your environments.)

You should have a pretty good idea at this point how you can structure your environments. It's important to note the following rules about environments before you start creating directories:

Once you've decided on a taxonomy, you need to create the directories. Go into the environments subdirectory under your data directory, and create them:

  # cd /opt/pwman_data/environments
  # mkdir prod
  # mkdir prod/billing
  # mkdir prod/billing/database 

(Yes, it's a bit tedious. Thankfully, you only have to do this once.) Tip: If you plan on using RCS, now might be a good time to create the RCS subdirectories too.


Now, you need to index and inventory your nodes. Each node that you want under control of pwman needs to exist in the nodes subdirectory, as a plain text file. The name of the file must be the fully-qualified domain name (FQDN) of the node. For example, let's say you have a node called; that is the name you'll use.

You need at least two attributes per node: a +ENV tag, and a +OS tag.

In our example, we now have a Node Control File (NCF) that looks like this:

You must create a NCF for each node that you want to manage. (Currently there isn't a tool for automatically creating NCFs; we'll write one soon enough.)

You probably want to check out the manpage for Covad::Pwman::Tags.


In order to install users onto nodes, you must first create a Role Control File (RCF) for the users, and add that role to the environment. To do this:

You now have an RCF called AdminUnixUsers that looks like this:

  alice:y:Regular employee:
  bob:y:Regular employee:
  carol:y:Regular employee:
  dave:y:Regular employee:
  ellie:y:Regular employee:

Now, you have to add the role to the environments you want them active in. Because this role needs pretty broad access (they do support all things UNIX-y, remember) we'll want to put them in the top of the environments. Role directives will inherit from parent roles, so to limit the number of places we want this role to appear, we can just put it into the top-level environment prod. To do this, we create a new file called role-users underneath the environments/prod directory.

  # cd /opt/pwman_data/environments/prod
  # touch role-users

...and add the following line to role-users:

  AdminUnixUsers y

The role AdminUnixUsers - which consists of alice, bob, carol, dave, and ellie, all of whom have full sudo access - will now be generated and installed on all nodes that are tagged with and environment of ``prod'', and any environment that exists underneath environments/prod.

Repeat this step for each role you wish to create.

System accounts

If you're fine with including system accounts via a role or group of roles, great. Roles are meant to be edited live by owners, however; this may not be desirable. To ensure that these accounts are not inadvertantly removed, this seperate classification exists.

Get a listing of the system users that you plan on propogating, and ensure that their usernames and user-ids are present in your authorative user database but do not conflict with real users. Move to the environment you want these users installed (for example, you'll want them in your prod tree) and create a file called system-users:

  # cd /opt/pwman_data/environments/prod
  # touch system-users

Add the system user account usernames to this file, one per line:


And that's done; these accounts will now be installed into the prod environment, and each environment underneath prod.


Once your configuration is complete, you can test the generation of nodes before you transfer to them. Move to the ``bin'' directory under your pwman instance, and run the ``'' script:

  # cd /opt/password_management/bin
  # ./

You should get the following usage message:

  Usage: ./ [-dvhCA] { -R | -E | -N } list
    -d  - debug on
    -v  - be verbose
    -h  - show this help message, then exit
    -C  - clear ALL work files, then exit
    -A  - audit only, do not generate any work files
  Node Selection:
    -R  - 'list' is interpreted to be Role Names
    -E  - 'list' is interpreted to be ENV environments
    -N  - 'list' is interpreted to be nodenames
  'list' in the above options is a comma ',' or space ' '
  seperated listing of things. Note: If 'list' is empty, then
  all things of that type will be generated.
  To push to all nodes in the 'production/sfs' and 'sqe/sfs' environments:
    ./ -E production/sfs sqe/sfs
  To push the roles 'AdminUsers' and 'BillingContractors':
    ./ -R AdminUsers, BillingContractors
  To push only this node:
    ./ -N
  To push *all* nodes:
    ./ -N
  To push *all* environments (but, you don't want to do this):
    ./ -E

Run it with -N nodename, where ``nodename'' is the FQDN of a node you've already indexed, to generate the ``work'' files for this node. Once it's complete, move to your work directory (under the DATA_DIRECTORY you specified), and examine the four work files: .passwd, .shadow, .sudoers, .digest:

  # ./ -N
  # cd /opt/pwman_data/work
  # ls*

The .passwd work file should match pretty closely to what you have on the live node; similarly with .shadow and .sudoers. The .digest file is a list of MD5 checksums of the other three work files.


If you're satisfied with the generated work files, you should transfer them out to the node. Use the script in the bin directory to do this:

  # cd /opt/password_management/bin
  # ./

Check any error messages, and once it's complete, log into the node and ensure that the specified accounts are installed and active.

See Also

``Applying RCS and SCCS'': Don Bolinger, Tan Bronson (, Nomenclature, the Covad::Pwman::Tags manpage, the Covad::Pwman::Parsers manpage, the Covad::Pwman::Roles manpage


Jon Gilbert <>


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