• Name
• Basic Installation
• Control Node Selection
• Prerequisites
• Getting the package
• Setting up a data directory
• Using revision control for your data
• Installation
• Configuration
• Properties
• Obtainment
• Environments
• Nodes
• Roles
• System accounts
• Testing
• Transfer
• See Also
• Author
• Version

Name

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).

Prerequisites

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.

• perl5, version 5.8.3
  
Note that 5.005_03 is fine for the nodes. Note also that 5.6 should work provided you upgrade FindBin and File::Temp.
• Config::Properties
  
Via CPAN at http://search.cpan.org/~salva/Config-Properties-0.61/
• Parallel::ForkManager
  
Via CPAN at http://search.cpan.org/~dlux/Parallel-ForkManager-0.7.5/
• Digest::MD5
  
Via CPAN at http://search.cpan.org/~gaas/Digest-MD5-2.33/
• LWP
  
Via CPAN at http://search.cpan.org/~gaas/libwww-perl-5.803/
• Net::SSH::Perl
  
Via CPAN at http://search.cpan.org/~dbrobins/Net-SSH-Perl-1.29/

Getting the package

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

  http://sourceforge.net/project/showfiles.php?group_id=150130

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

  /opt/pwman_data

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.)

Installation

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 ./install_password_management.pl 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.

Configuration

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

Properties

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 pwman.properties. 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:

• pwman.path
  
Password Management needs certian binary installations that may not be in your PATH. In particular, if you're going to be using revision control (like CVS or RCS), you should ensure that these tools are in the default PATH for root. If that's not feasible, then you can extend the PATH for Password Management tools and applications with this property.
• pwman.inc
  
If you put your perl modules and libraries in a non-standard location (most people put them into /usr/lib/perl or /usr/local or some such nonsense), then you can add to the @INC here. (Basically, if you had to modify PERL5LIB during installation, then you should put the same values here.)
• pwman.ldpath
  
If for whatever reason you have shared libraries that need to be loaded in a non-standard place (for example, libgmp - which is required by Net::SSH::Perl), you can add that location here instead of changing the LD_LIBRARY_PATH environment variable each time you need it.

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.

Obtainment

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 password_generator.pl, 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 pwman.pg.obtain.use_first_match).

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

• obtain_pre_hacks
  
Transforms ``hacks'' entries into actual accounts.
• obtain_post_debugging
  
Creates dummy accounts with random UID/GIDs and bogus data. It's useful for debugging or testing but not at all appropriate for normal use.
• obtain_post_NIS_covad
  
This is a plugin that just simply calls ypmatch for a given username, and splits out the appropriate info. It's a pretty decent example of how obtainment should work, but it's also very simple.

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:

• obtain_pre_hacks
  
• obtain_post_NIS_covad
  

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.

Environments

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:

• allowed characters: [a-zA-Z0-9-_]
  
Each part of an environment name can only contain letters, numbers, underscore _, and horizontal dashes -. Environment names may not begin with an underscore _ or a horizontal dash -.
• case
  
Environment names are case sensitive: ``dev'' and ``Dev'' are different environments.
• length:
  
There's no hard length for environments, or individual environment parts. However, you'll want to keep them as short as possible (without leading to confusion or over acronymimity), because it's a fair bet that you'll be typing them frequently soon enough.
• depth
  
There's no hard limit in Password Management as to how deep your environment tree can go. However, there may be a filesystem limitation - environments are represented as a hierarchial directory structure directly on the filesystem - so check out your man pages (I believe that ext3 limits absolute pathnames to 255 characters; UFS under BSD limits the number of directories under a single subdirectory to 32,768; YMMV based on vendor and FS implementation). This probably won't be a problem for you, unless you really need a Password Management installation that large, and if you do, please contact me, because I'd be curious how your performance is. ;)

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.

Nodes

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 www01.domain.com; that is the name you'll use.

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

• +ENV={environment}
  
The +ENV tag specifies the environment this node belongs to. {environment} is one of the environments you created under the environments directory. You can have multiple environments, seperated by a comma-whitespace, like so:

  +ENV=prod, prod/billing

Or you can have multiple lines, like so:

  +ENV=prod
  +ENV=prod/billing

• +OS={os_specification}
  
The +OS tag defines what operating system, machine architecture, and revision this node runs. It's syntax looks like this:

  os_name/machine_arch/os_version

For example, if you have a Solaris 8 node running on Sparc, the os_specification would look like:

  solaris/sparc/5.8

You can only have one +OS tag per node.

The following operating systems are known:

• solaris
  
• linux
  
• cyclades
  

The following architectures are known:

• sparc
  
• x86
  
• amd64
  
• ppc
  

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

  www01.domain.com:
  -----------------
  +ENV=prod
  +OS=solaris/sparc/5.7

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.

Roles

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:

• Create the RCF
  
Move into the roles directory under the DATA_DIRECTORY you specified above, and create a new text file (for example, we'll call it AdminUnixUsers).

  # cd /opt/pwman_data/roles
  # touch AdminUnixUsers

Role names may not begin with an underscore _.

• Assign a role owner
  
Add the following +OWNER tag to the top of the AdminUnixUsers RCF. In our example, the ``owner'' of the role will be ``alice''; she's the person responsible for this group of users in this role capacity (in other words, Alice is the user that would manage the members of the UNIX Admin users).

  +OWNER=alice

• Assign sudo commands and runas users
  
Add the following +SUDO_RUNAS and +SUDO_CMDS tags for the AdminUnixUsers RCF. In our example, the UNIX Admin users are responsible for all things UNIX-y, so we give them pretty broad permissions.

  +SUDO_CMDS=ALL
  +SUDO_RUNAS=ALL

• Add the users
  
For each user that acts in the capacity of UNIX administration, under direction of Alice, add them.

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

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

  +OWNER=alice
  +SUDO_CMDS=ALL
  +SUDO_RUNAS=ALL
  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:

  daemon
  bin
  sys
  sync
  man
  lp
  uucp
  backup

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

Testing

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 ``password_generator.pl'' script:

  # cd /opt/password_management/bin
  # ./password_generator.pl

You should get the following usage message:

  Usage: ./password_generator.pl [-dvhCA] { -R | -E | -N } list
  Options:
    -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.
  
  Examples:
  To push to all nodes in the 'production/sfs' and 'sqe/sfs' environments:
    ./password_generator.pl -E production/sfs sqe/sfs
  To push the roles 'AdminUsers' and 'BillingContractors':
    ./password_generator.pl -R AdminUsers, BillingContractors
  To push only this node:
    ./password_generator.pl -N it-inf01.corp.covad.com
  To push *all* nodes:
    ./password_generator.pl -N
  To push *all* environments (but, you don't want to do this):
    ./password_generator.pl -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:

  # ./password_generator.pl -N node.domain.com
  ...
  # cd /opt/pwman_data/work
  # ls node.domain.com.*
  node.domain.com.digest      node.domain.com.passwd
  node.domain.com.shadow      node.domain.com.sudoers

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.

Transfer

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

  # cd /opt/password_management/bin
  # ./password_xfer.pl node.domain.com
  ...

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 (http://www.oreilly.com/catalog/rcs/colophon.html), Nomenclature, the Covad::Pwman::Tags manpage, the Covad::Pwman::Parsers manpage, the Covad::Pwman::Roles manpage

Author

Jon Gilbert <jong@jong.org>

Version

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