h61436 s 00003/00003/00466 d D 1.17 00/06/10 16:15:08 clyde 17 16 c Change gzip to gunzip e s 00001/00001/00468 d D 1.16 98/09/14 13:16:54 clyde 16 15 c Change pathname for dist package e s 00005/00005/00464 d D 1.15 98/07/20 15:52:41 clyde 15 14 c Spell check e s 00017/00000/00452 d D 1.14 98/07/20 15:16:09 clyde 14 13 c Mention what the package builds e s 00000/00017/00452 d D 1.13 98/07/20 14:39:25 clyde 13 12 c Remove passwd history group stuff e s 00018/00001/00451 d D 1.12 98/07/16 14:51:18 clyde 12 11 c Add part about history database group query e s 00009/00003/00443 d D 1.11 98/07/16 09:12:34 clyde 11 10 c 1. Update path tokens c 2. Add note about multiple visits to dirs during build e s 00003/00003/00443 d D 1.10 98/07/09 15:27:44 clyde 10 9 c Fix link typo e s 00177/00187/00269 d D 1.9 98/07/08 17:01:59 clyde 9 8 c Edit cleanup e s 00002/00290/00454 d D 1.8 98/07/02 15:02:22 clyde 8 7 c Remove Internals section e s 00540/00115/00204 d D 1.7 98/07/02 14:09:27 clyde 7 6 c Major revision e s 00035/00003/00284 d D 1.6 98/06/30 12:22:04 clyde 6 5 c Add part on test suite and bug fixes e s 00002/00002/00285 d D 1.5 98/06/30 10:32:45 clyde 5 4 c Change title e s 00008/00009/00279 d D 1.4 98/06/26 09:56:13 clyde 4 3 c Fix signatures e s 00002/00002/00286 d D 1.3 98/06/25 16:32:28 clyde 3 2 c Change name to Programmers Guide e s 00056/00084/00232 d D 1.2 98/06/25 16:01:57 clyde 2 1 c Move installed files table to admin guide e s 00316/00000/00000 d D 1.1 98/06/24 17:22:02 clyde 1 0 c date and time created 98/06/24 17:22:02 by clyde e u U f e 0 t T I 1 D 2 Npasswd: Internals E 2 I 2 D 3 Npasswd: Developers Guide E 3 I 3 D 5 Npasswd: Programmers Guide E 5 I 5 D 7 Npasswd: Programmer's Guide E 7 I 7 D 8 Npasswd Technical Manual E 8 I 8 Npasswd Build and Install E 8 E 7 E 5 E 3 E 2 I 4 E 4
D 2

Internals

E 2 I 2 D 3

Developers Guide

E 3 I 3 D 5

Programmers Guide

E 5 I 5 D 7

Npasswd: Programmer's Guide

E 7 I 7 D 8

Npasswd Technical Manual

E 8 I 8

Npasswd Build and Install

E 8 E 7 E 5 E 3 E 2 D 2

E 2 I 2 D 4 E 2 E 4

I 7

System Requirements

D 9 To build and install npasswd, the following are needed:

E 9

D 9


E 9 I 9
E 9

I 14

About the package

The npasswd package produces the following components which share infrastructure and code:


E 14

About the distribution

D 10 The full list and description of files in the distribution is in the package MANIFEST. E 10 I 10 The full list and description of files in the distribution is in @NPASSWD-SRC@/MANIFEST. E 10

D 9

E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 E 9 D 9 E 9 D 9 E 9 D 9 E 9 I 9 E 9 D 9

Special files in the distribution

Files in the distribution

ConfigureScript which probes system facilities and performs package setup.
Produces config.sh and expands all .SH files in the distribution. See About Configure.
Script which probes system facilities and performs package setup.
Produces config.sh and expands all .SH files in the distribution. See About Configure.
config.shShell script which contains settings from Configure.Shell script which contains settings from Configure.
config.hC include which contains settings from config.sh.
config_h.SHShell script which creates config.h.
Makefile.SHShell script which creates Makefile with settings from config.sh
*.SH Shell script which produces a file with settings from config.sh

Directories in the distribution

Directories in the distribution

developer Files needed for developers.
This directory is a part of the developers kit.
dict Dictionary sources, which are a seperate distribution.
doc
Documentation (text, manual pages, HTML)
hints Platform-specific hints for use by Configure.
files Configuration, help and messages files.
src Top-level sources.
  src/Common Common object library sources.
  src/Methods Password database method module source.
  src/Methods/TestSuite Test suite for passwd database method modules.
  src/Scripts Utility script sources.
  src/PasswordCheck Password check library source.
  src/PasswordCheck/cracklib Crack library.
  src/PasswordCheck/cracklib/tools Crack library testing and dictionary tools.
E 9 I 9 developer Developer support files.
D 10 These are in the developers kit. E 10 I 10 These are in the developers kit. E 10 dict D 15 Dictionary sources (which are a seperate distribution). E 15 I 15 Dictionary sources (which are a separate distribution). E 15 doc Documentation (text, manual pages, HTML) hints Platform-specific hints for Configure. files Configuration, help and message files. src Main sources.   src/Common Common object library sources.   src/Methods Password database method module source.   src/Methods/TestSuite Test suite for passwd database method modules.   src/Scripts Utility script sources.   src/PasswordCheck Password check library source.   src/PasswordCheck/cracklib Crack library.   src/PasswordCheck/cracklib/tools Crack library testing and dictionary tools. E 9

D 9


E 9 I 9
E 9

D 9

About Configure

E 9 I 9

About Configure

E 9

D 9 Configure is a shell script which probes the system environment to determine how to build npasswd. Configure itself is built using the Metaconfig software configuration package. E 9 I 9 Configure is a shell script which probes the system environment to determine how to build npasswd. E 9 D 9

Configure will determine what kind of system it is running on, features E 9 I 9

It will determine what kind of system it is running on, features E 9 D 15 available and idiosyncrasies of the C compilation environment. E 15 I 15 available and idiosyncrasies of the C compiliation environment. E 15 D 9

The result of Configure is config.sh, which contains shell variable settings which will be incorporated into other files. Every file ending with ".SH" is a script which, when run, produce a source file with settings from config.sh. E 9 I 9

The result of running Configure is config.sh, which contains shell variable settings which will be incorporated into other files. Every file ending with ".SH" is a script which, when run, produce a source file with settings from config.sh. E 9 D 9

If you are doing porting or development work on npasswd, refrain from making changes to Configure. Fetch the developer kit and modify the Metaconfig units from which Configure is built. It is a lot easier to integrate changes to Metaconfig units rather than determine which unit E 9 I 9

Configure itself is built using the metaconfig software configuration package. If you do porting or development work on npasswd, fetch the developer kit and modify the metaconfig units from which Configure is built. It is a lot easier to integrate changes to metaconfig units rather than determine which unit E 9 a particular Configure change affects. D 9

E 9

I 9

E 9


I 9

E 9 D 9

Interacting with Configure

E 9 I 9

Interacting with Configure

E 9

For most of the questions you are asked by Configure, taking the default is sufficient. Some of the questions require your attention, especially the first time Configure is run.

Use which C compiler? [cc]
D 9
Any ANSI C compiler can be used - gcc is fine. Npasswd will also build with non-ANSI compilers, but this is discouraged.
E 9 I 9
Any ANSI C compiler can be used - gcc is fine. Npasswd should also build with non-ANSI compilers, but this is discouraged.
E 9

Do you expect to run these scripts and binaries on multiple machines? [n] D 9

Always answer n
E 9 I 9
Always answer n
E 9

Pathname where the private library files will reside?

This is the install directory where npasswd and its ancillary D 9 files will be placed. If the system is a NFS server for workstations, this directory should be put on a file system that clients mount read/write (preferably with root access). For standalone systems the default (/usr/lib/npasswd) is reasonable.
E 9 I 9 files will be placed. The default is /usr/lib/npasswd.
E 9

### Found passwd files "/etc/passwd"
Change passwd file list? [n]

Npasswd can search multiple local password files to find a user. If you want to manipulate non-standard password files, specify them here.

### Found shadow files "/etc/shadow"
Change shadow file list? [n]

Npasswd can search multiple local shadow files to find a user. If you want to manipulate non-standard shadow files, specify them here.

Replace system programs? [y]

If this option is selected, then Configure creates a list of the programs in system bin directories which have "passwd", "chfn" or "chsh" in their names. You will be able to edit this list. The initial installation will move these programs will be moved to the npasswd install directory.

D 9 Do you wish to build the test version? [y]

Choose this option if you are doing development or serious debugging.

E 9 Activate the "paranoid" option [n]

Activating the paranoid option will cause npasswd to abort if the uid obtained via getpwnam(getlogin()) is not the same as that returned by getuid(2). If you allow multiple login names to have the same uid, DO NOT enable this option.

Password history file [/usr/lib/passwd/history] D 9

If this system is a workstation server, this file needs to be on a file system that clients can write to.

Primary dictionary directory [/usr/lib/passwd/dictionaries]

Select where to put the default dictionary collection.
E 9 I 9
If this system is a member of a cluster which shares a password file, the history should be put on a file system that all cluster members mount read/write, preferably with root access. I 12
E 12 Refer to the password history section of the Npasswd Administration Guide.
E 9 D 12 E 12

I 12 D 13 Group for history database [nobody]

The history database is protected from prying eyes by granting read-write access only to the owner and read-only access for the group. Group permissions are used to alleviate the need for programs which require history database access (e.g. checkpassword) to run as root. The database will be readable by this group and the checkpassword program will be set-gid to it.
The preferred group for this purpose is one which does not own system files. The default is group nobody.
Refer to the password history section of the Npasswd Administration Guide.

E 13 E 12


D 9 E 9

D 9

Building

E 9 I 9

Building

E 9

D 9 If the system has symbolic links, it a good idea to use a "build tree" to keep the source area clean. Such a tree can be constructed with the BuildTree script. E 9 I 9 If your system has symbolic links, it is a good idea to use a "build tree" to keep the source area clean. The BuildTree script will do this. E 9

D 11

E 11 I 11

Note about the build process

During build process some directories will be visited multiple times. D 15 This is because of the dependancies between various parts of E 15 I 15 This is because of the dependencies between various parts of E 15 the package.

E 11 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 Most depend targets do make depend in subdirectories. E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9 D 9 E 9 I 9 E 9

Common make targets

helpSee what package targets are available.
See what package targets are available.
allBuild the default stuff, whatever that may be. Most all targets do make all in various subdirectories.
Build the default stuff, whatever that may be. Most all targets do make all in subdirectories.
dependUpdate the C source dependancies. A modified Makefile is created E 9 I 9 D 15 Update the C source dependancies. A modified Makefile is created E 9 which has the dependancy information at the end. E 15 I 15 Update the C source dependencies. A modified Makefile is created which has the dependency information at the end. E 15 D 9 Most depend targets do make depend in various subdirectories.
installInstall what is built in this directory. Most install targets do make install in various subdirectories. Install what is built in this directory. Most install targets do make install in subdirectories.
deinstallRemove what is built in this directory. Most deinstall targets do make deinstall in various subdirectories.
Remove what is built in this directory. Most deinstall targets do make deinstall in subdirectories.
cleanLight debris removal.
Light debris removal.
realcleanTotal cleanup of debris, object files and executables.
Total cleanup of debris, object files and executables.

Special make targets

E 9 I 9

Special make targets

These targets alter the compile and load flags in Makefile.local, which is included by the Makefile. They also do recursive makes in subdirectories.
(See the Support Guide for details) E 9
debug-none Create production binary (default). The -XD command line option is still available for run-time debugging. debug-none Build production executables. The -XD command line option is available for run-time debugging.
debug-dbx Build binary with symbol table for source debugger.debug-dbx Build production executables with source debugger support.
debug-files Build debugger binary and enable use of files in current directory.
Used to test update code without changing system files.
debug-files Build debug-dbx executables which change files in the current directory.
debug-system Build debugger binary, enable use of files in current directory and disable some update and security checks.
This binary is insecure and partly non-functional and NOT suitable for production.
debug-system Build debug-system executables with many security and update checks disabled.
These executables are insecure, partly non-functional and are NOT suitable for production.
D 9


E 9

D 9

Customizing

E 9 I 9
E 9

D 9 Most customizations should be done by re-running Configure. However, there are some some changes which requires modification of options.h in the top-level source directory. The file to edit is options_h.SH. E 9 I 9

Customizing

E 9

I 9 Major customizations can be done by running Configure. Some changes require modification of options.h. The file to edit is options_h.SH.

E 9 Follow this procedure: D 9

E 9


Installing

D 9 Do make install in the top build directory. E 9 I 9 Invoke make install in the top-level build directory. E 9

E 9 I 9
  • The install will create any needed directories.
  • Dictionary hash files will be built. The word list distribution must have been unpacked into the dict directory first.
  • Executables and ancillary files are placed in the install directory.
  • If replace system programs was selected, the system password change utilities found by Configure will be saved and replaced with copies or links to the npasswd binary. E 9


    Removing

    To reinstall the vendor password programs, D 9 run npasswd-lib/restorefiles. E 9 I 9 D 11 run @NPASSWD-LIB@/restorefiles. E 11 I 11 run @NPASSWD-UTIL@/restorefiles. E 11 E 9

    To reinstall the vendor programs and delete npasswd, do D 9

    E 9 in the top build directory. If the replace vendor programs option was not enabled, the system utilities are not affected by the removal process.


    Build and install summary

    The procedure to build, install and setup npasswd:

    D 8


    Troubleshooting

    Tactics for troublshooting:


    Bug reports

    If you find a bug, send the report to npasswd-bugs@lists.cc.utexas.edu. Please use the bug report template BugReport.html.

    The more information you can provide in the bug report, the better chance of getting a fix. The developer has a limited variety of UNIX platforms available for devlopment and testing.

    Support will be done on a time-available basis.


    Bug fixes

    If you fix a bug, sent the change to npasswd-bugs@lists.cc.utexas.edu.

    The preferred form is a context diff between the distribution and the modified sources (e.g. diff -c dist-src new-src).

    Do not make changes directly to files which are generated from .SH files. The next time that Configure is run, those changes will be lost. Modify (and submit changes to) the .SH file instead.

    Changes to the Configure script are more complicated. It is built from many files (see below), so changes should be made to those sources. If you need to make serious modifications to Configure, obtain the developer kit, modify the metaconfig units and submit those changes. Minor changes can be reported by a context diff on Configure.


    E 7 D 2

    Introduction

    E 2 I 2

    Internals

    E 2 This is a quick overview of the internals of npasswd. It is not a full documentation of the entrails, but is a supplement to the ultimate documentation - the source code. D 2 E 2

    D 2


    Program structure

    E 2
    User layer User interface
    &
    Configuration sub-system
    passwd
    sub-program

    Password check library
    chsh
    sub-program
    chfn
    sub-program
    Password method switch
    Method layer
    NIS
    method module
    Local passwd
    method module
    NIS+
    method module
    SunOS adjunct
    method module
    System 5 shadow
    method module
    DEC auth
    method module
    Utility layer
    "Common object" library
    D 7

    E 7 I 7

    E 7


    D 2

    Design philosophy

    E 2 I 2 D 7

    Design philosophy

    E 7 E 2

    D 7 Guiding philosophies for the design: E 7 I 7

    Design philosophy

    E 7

    D 7

    Source distribution

    E 7

    D 7 The full list and description of the distribution is in the package MANIFEST file.

    developer Files needed for developers.
    D 2 This directory is included only in the developer distribution. E 2 I 2 This directory is included only in the developers kit. E 2
    dict Dictionary word lists.
    The word lists are in a seperate distribution.
    doc
    Documentation files.
    hints Platform hints for use by Configure.
    files Ancillary sources,
    src Npasswd sources.
      src/Common Common object library sources.
      src/Methods Password database method module source.
      src/Methods/TestSuite Test suite for passwd database method modules.
      src/Scripts Utility script sources.
      src/PasswordCheck Password check library source.
      src/PasswordCheck/cracklib Crack library.
      src/PasswordCheck/cracklib/tools Crack library testing and dictionary tools.
    E 7


    I 6 D 7

    Test suites

    E 7

    D 7 Test suites are provided for various parts of npasswd. These C programs and shell script drivers are throughout the distribution in directories and scripts named TestSuite. If changes are made to any part of npasswd which has a test suite, that suite should be run to verify that the changes didn't break the basic functionality. If new functionality is added, then the test suite should be modified to verify it.


    Bug fixes and contributions

    Bug fixes and changes should be sent to the address noted in the support section of the manual.

    The preferred form is a context diff between the distribution and the modified sources (e.g. diff -c dist-src new-src).

    Do not make changes directly to files which are generated from .SH files. The next time that Configure is run, those changes will be lost. Modify the .SH file instead.

    Changes to the Configure script are more complicated. It is built from many sources (see below for a quick overview), so changes should be made to those sources. If you need to make serious modifications to Configure, obtain the developer kit, modify the metaconfig units and submit those changes. Minor changes can be reported in the usual way.


    E 7 E 6 D 2

    Files Installed

    E 2 I 2 D 7

    Developer resources

    E 7 I 7

    Developer information

    E 7 E 2

    D 2 The following files and directories are used by npasswd. These paths (except the configuration file) can be changed by directives in the configuration file. E 2 I 2 The npasswd kit is built using the dist package - a set of tools meant to ease the construction and maintenance of portable software. E 2

    D 2 E 2 I 2 The central component of which is the Configure script generator, metaconfig. This program scans source files, feature files (units), and builds a Configure script. Configure probes the system, requests information from the user, and saves the results for use in customizing the package.

    The end-user reads the README file, runs the Configure script (which is self-documented), and then make.

    The jmake program is used to build Makefiles. It reads a Jmakefile and produces a shell script which takes the configuration data from Configure, to produce a customized Makefile.

    D 7 There are a number of files in the distribution which end with .SH. These are scripts which takes configuration data and build customized files (e.g. C header files and shell scripts). E 7 I 7 Changes to Configure are really changes to metaconfig units. Changes to a Makefile are really changes to the Jmakefile source. E 7

    The end-user package does not include the dist sources (Jmakefiles, metaconfig units) and glue files. These make up the Npasswd Developers Kit.

    D 7 Changes to Configure are really changes to metaconfig units, from which Configure is built. Changes to a Makefile are really changes to a Jmakefile, from which the Makefile is built. E 7 I 7 Verification suites are provided for various components of npasswd. These C programs and shell scripts are usually named (or in a directory named) TestSuite. If you change any part of npasswd which has a test suite, run that suite to verify that your changes didn't break the basic functionality. If you add new functionality, modify the test suite and submit the changes. E 7

    D 7 To do serious work on npasswd, the developers kit is a necessity. E 7 I 7 For serious work on npasswd, the developers kit is a necessity. E 7

    D 4

    Getting the the developer kit

    E 4 I 4 D 6

    Getting the developers kit

    E 6 I 6 The developers kit is available at: E 6 E 4

    D 6 The developers kit is available from:

    E 6

    I 7

    E 7 E 2 E 8 D 2

    Default locationWhat it is
    /usr/lib/passwd Directory where all the parts live
    /usr/lib/passwd/xbin Directory where vendor utilities are saved
    /usr/lib/passwd/dictionaries Directory where the hashed Crack dictionaries live
    /usr/lib/passwd/doc Directory for npasswd documentation
    /usr/lib/passwd/passwd.conf The npasswd configuration file
    /usr/lib/passwd/chfn.help
    /usr/lib/passwd/chfn.motd
    Help and message-of-the-day for chfn sub-program
    /usr/lib/passwd/chsh.help
    /usr/lib/passwd/chsh.motd
    Help and message-of-the-day for chsh sub-program
    /usr/lib/passwd/passwd.help
    /usr/lib/passwd/passwd.motd
    Help and message-of-the-day for passwd sub-program
    /usr/lib/passwd/history Password history database
    E 2


    D 4

    Manual HomeTop of page E 4

    I 4 Top    Home

    E 4


    Document id %Z% %M% %I%
    Version %I%
    Last modified %G%

    D 4 Clyde Hoover
    E 4 I 4 D 9 Clyde Hoover
    E 9 I 9 Clyde Hoover
    E 9 E 4 Academic Computing Services and Instructional Technology Services
    The University of Texas at Austin
    Copyright 1998, The University of Texas at Austin. All rights reserved. I 4 E 4 E 1