nsbd man page
SYNOPSIS
nsbd {-help | -?} [topic]
nsbd {-version | -V | -license}
nsbd [*] [-unsigned|-wait4signature] [-askreason] [-cvsExclude] [*]
{file.npd|-}
nsbd [**] -register {URL | file.nsb | -}
nsbd [**] {-update | -poll | -audit} {all | {[*] package [...]}}
nsbd [**] {-preview | -fetchAll} {[*] {package | URL | file.nsb | -}}
[...]
nsbd [*] {-remove | -unregister} {[*] package [...]}
nsbd {{-multigetFiles [directoryPrefix]} | {[*] -multigetPackage pack-
age}}
nsbd [**] {-updateOnePackage | -changedPaths | -batchUpdate} package
nsbd [*] -updateComments {file.ncf | file.nrd | file.npd | file.nsb}
nsbd [*] {-getPathPackages | -getRegisteredPathPackages} glob_pattern
[...]
nsbd [*] -getPackagePaths package [....]
nsbd [*] -getPackageRegistryKey package key
nsbd {-signFile file} | {-getUrl URL} | {-postUrl URL}
nsbd registryFiles=infile.nrd[,...] -dumpRegistry outfile.nrd
nsbd configFiles=infile.ncf[,...] -dumpConfig outfile.ncf
[*] indicates any keyword=value.
[**] indicates same plus "-ignoreSecurity".
"-" indicates standard input.
DESCRIPTION
NSBD, Not-So-Bad Distribution, is an automated distribution system that
is designed for distributing open source software on the internet,
where users cannot trust the network and cannot entirely trust the
maintainers of software. NSBD authenticates packages with GNU Privacy
Guard (GnuPG) or "Pretty Good(Tm) Privacy" (PGP(Tm)) digital signatures
so users can be assured that packages have not been tampered with, and
it limits the maintainer to only update selected files and directories
on the user's computer. NSBD's focus is on security, leaving as much
control as is practical in the users' hands.
To accomplish the automated updates, NSBD supplies a means of checking
for updates to packages and automatically downloading and installing
the updates. This "automated pull" style of distribution has the same
effect as the "push" style of distribution that is being given press
lately, but gives more control to the user. A direct "push" style is
also supported which is not used as frequently but which is especially
appropriate for situations where there are multiple contributors to a
shared server (for example, a shared web-page server). NSBD can "pull"
directly over http or by using rsync to minimize network usage.
This is the basic operation: maintainers of packages make their files
available at some http or ftp URL, create a Nsbd Package Description
'.npd' file to describe the files, and run NSBD interactively with that
'.npd' file to indicate that they have approved the files. That step
creates a Not-So-Bad '.nsb' file which contains the URLs for all files
in the package, MD5 or SHA1 message digests for each file (also known
as secure hashes; they're like checksums, only with much better secu-
whose message digest information has changed will be loaded. If all
the loaded files match the message digest information, they will be
installed where the user wants them, and files that have been removed
from the package will be removed from the user's copy. The user is
thus assured that no matter how insecure the network, only updates from
the authorized maintainer will be automatically installed because only
the authorized maintainer controls the PGP or GPG private key. The
user is also assured that if multiple files have changed they will be
installed all together or not at all. (Detail note: in order to be
valid, the timestamp on a '.nsb' file has to be newer than the times-
tamp on the previous one, to avoid the unlikely case of a spoofer
installing an old valid '.nsb' file in a "replay attack").
Alternatively, if only a small number of users (typically one) are
expected for a package, users may permit maintainers of packages to
directly "push" package updates as opposed to the "automated pull" of
'nsbd -poll'. To use this mode of operation, the user(s) install sup-
plied CGI scripts and the maintainers invoke them to directly send in
updates rather than making the package available at a URL (see the
-batchUpdate option). The same security model applies in either mode
of operation.
By using the included program breloc, NSBD can also relocate binary
packages so they can be installed at a location of the user's choice,
if the binary packages are configured with a "prefix" that has a suffi-
cient number of trailing slashes to accomodate the user's chosen loca-
tion.
GETTING STARTED
When you run nsbd the first time, it will create ~/.nsbd/config.ncf and
~/.nsbd/registry.nrd for you and will ask you where your PGP or GPG is
and if you want to auto register for NSBD binary updates. It will also
ask you if you want it to add a line to your $HOME/.mailcap of the form
application/x-nsbd; $HOME/nsbd/bin/nsbd -register %s
to be used for launching nsbd from a web browser to register for pack-
ages.
If you are only a user of packages and not a maintainer, you don't need
to worry about most keywords and you can completely ignore the '.npd'
and '.nsb' files. You should just peruse the configuration file key-
words to see if some of them seem useful to you. Almost all the key-
words in the Registry Database are filled in from the window that pops
up when you register a package with -register, and you should probably
try to understand most of those (there is also pop-up help for those).
If you are a maintainer of packages, you will need to understand the
keywords in the '.npd' files. To create a template package description
file with a comment for each keyword, create a new '.npd' file with the
line "nsbPackageDescription: 1" and run "nsbd -updateComments" on the
file. If you want to make your package available on the web, you
should also look at the lib/nsbd directory for some helpful CGI scripts
you may want to use.
or GPG keys.
SECURITY MODEL
The fundamental security model of NSBD is that the user retains control
and only gives away as much authority as necessary to get the update
job done but no more. Only authenticated updates from authorized main-
tainers are accepted, files are only installed into authorized loca-
tions on the user's disk, and only authorized commands are run during
installation. Maintainers may include in their package suggested val-
ues for all of the installation parameters, but it is up to the user to
accept them. Alternatively, users may selectively give away additional
privileges to maintainers to allow them to remotely update most of the
installation parameters, depending on how much they trust the maintain-
ers (see "maintainerUpdatableKeys").
These are the installation parameters related to security for each
package; see also the descriptions of each keyword in the different
NSBD files:
1. maintainers - the list of PGP/GPG user ids of authorized maintain-
ers that may install updates.
2. installTop - the top level directory in which to install files
into. No complete paths or ".." components are allowed in
installed paths, so all files will be strictly below this direc-
tory.
3. validPaths - list of files and directories underneath installTop
that may be written.
4. preUpdateCommands/postUpdateCommands - arbitrary commands to exe-
cute before and after installation of an update.
If the maintainer suggests values for any of these parameters, users of
packages need to realize that the packages may not work properly if
they decide to set the parameters to something else.
Note that if executable programs are distributed and the user executes
those programs after installation is complete, that program will have
all the same access privileges that the user has. However, if instal-
lation is done under a privileged user id or on a trusted server which
don't execute the programs themselves, the users can at least trust
that the programs won't interfere with each other. For example, if an
untrustworthy maintainer is trusted to install an infrequently-used
program, users can at assume that other programs installed under the
same privileged user id will not be tainted by the bad program.
Another important part of the security model is that it is designed to
be useful for redistribution. For example, Bell Labs has a redistri-
bution system called "Exptools" in which individuals around the company
are permitted to install packages onto the master copy of the distribu-
tion system. From there, the packages are distributed to a large num-
ber of servers. The NSBD ".nsb" files, on which the original maintain-
ers have manually applied digital signatures authorizing all files in
-version or -V
Print the current program version.
-license
Print the license (GNU General Public License) and no-warranty
details.
-register
Register package described in the '.nsb' file at following filename
or URL. URL may be of type http://, ftp://, rsync://, or file://.
Pops up a window to request verification of package registry infor-
mation before registering and installing. If a Graphical User
Interface display is not available, register package by hand by
editting 'registry.nrd' with information from the package's '.nsb'
file and use '-update' on the package.
-update
Check registered packages for updates and install the updates. If
package name is the special name "all", will check all registered
packages. Here is a special case useful for installing packages
from within a single computer: if nsbUrl and topUrl are specified
on the command line with a URL type of file:// (and there's no
multigetUrl), files will be installed from a local filesystem
rather than over a network.
-updateOnePackage
Same as -update except that only one package may be checked and no
command line keyword settings are supported after the option; for
use by remote invocation from a CGI script.
-poll
Same as -update, except only polls registered packages whose min-
PollPeriod has elapsed. If package name is the special name "all",
will poll all registered packages.
-preview
Preview the following packages, either registered package names or
'.nsb' files (local or at URLs), displaying which files are ready
to be installed or removed. Note that if you preview a '.nsb' file
for a package that is not registered, you will not be prompted for
installation choices so defaults will be used.
-fetchAll
Fetch all the following packages, either registered package names
or '.nsb' files (local or at URLs), and verify that all files can
be fetched and that the checksums match those that are in the
'.nsb' files. Each '.nsb' itself file will also be verified to be
identical to the one referred to by the 'nsbUrl' keyword in the
file. This is useful for maintainers of packages to test their
packages without installing anything.
-audit
Audit registered packages to compare installed files with what the
'.nsb' say should be installed. The configuration keyword "audi-
format" (a simple MIME-like protocol) to standard output. Path
names are relative to the the directory from which NSBD is invoked.
The optional parameter is a directory prefix to prepend to each
path name. This is intended to be used from a CGI script that is
invoked with an http POST operation, to return files for the
"multigetUrl" '.nsb' file keyword. If the environment variable
$CONTENT_LENGTH is set and non-empty (which it will be in a CGI
that is invoked with http POST), at most that many bytes will be
read from standard input. Typical usage in a script is:
#!/bin/sh
cd top_directory; exec nsbd -multigetFiles "$QUERY_STRING"
which will pass in any "?" parameter given at the end of the URL.
All paths (including the prefix) must be relative paths and
strictly below the directory from which NSBD is invoked (that is,
no ".." components are allowed). Note: this is really a simple
function that could be a program separate from NSBD, but it is a
subset of -multigetPackage and it is easier to maintain here than
as a separate program.
-multigetPackage
This is similar to -multigetFiles except that files are read from
where they have been installed by NSBD as part of a package. This
is intended for redistribution of packages. The parameter is a
registered package name. A typical usage in a CGI script is:
#!/bin/sh
NSBDPATH=~yourlogin/.nsbd; export NSBDPATH
exec nsbd executableTypes="$PATH_INFO" -multigetPackage "$QUERY_STRING"
The CGI variable $PATH_INFO comes from the stuff in a URL immedi-
ately following a CGI script with a "/", and $QUERY_STRING comes
from stuff following a "?" after that. For example, the URL
http://any.com/cgi-bin/multiget/etype?pname
gets a $PATH_INFO of /etype and a $QUERY_STRING of pname assuming
multiget is a CGI script. A leading slash on executableTypes is
ignored here.
-changedPaths
Display list of paths that have changed for the following regis-
tered package compared to the '.nsb' file which is sent to standard
input. This is intended to be used from a remote CGI script (see
supplied posttonsbd.sh) to return the list of files that should be
sent to the -batchUpdate option. Note that, like anytime NSBD
files are read from standard input, if the environment variable
CONTENT_LENGTH is set and non-empty (which is standard on http POST
operations to CGI scripts) then NSBD will read at most that many
bytes. The list of paths returned is preceeded by a line that has
5 dashes, BEGIN CHANGED PATHS, and 5 dashes, and the list is fol-
lowed by a line that has 5 dashes, END CHANGED PATHS, and 5 dashes.
-batchUpdate
Do a batched update of the following registered package. Standard
input is expected to contain a '.nsb' file, followed by a separator
line that has 5 dashes, BEGIN BATCH UPDATE, and 5 dashes, and by
all of the changed files in the format used by the nsbd -multiget
option. This is intended to be used from a remote CGI script; see
-unsigned
Do not put a PGP signature when creating a '.nsb' file from a
'.npd' file. WARNING: Use carefully, only when your users can
trust the network over which they retrieve your '.nsb' file. This
must be before the '.npd' file on the command line.
-wait4signature
Like -unsigned, but wait for a detached PGP signature file to
appear with an extension '.nsb.sig' and then move the signature to
the '.nsb' file. This is useful for people who have their PGP
installed on a separate computer such as PC but run nsbd on a Unix
server.
-askreason
When creating a '.nsb' file from a '.npd' file, prompt the user for
a reason for an update, to put into the "releaseNote" keyword in
the '.nsb' file. Offer the opportunity to escape to the editor set
in $EDITOR (default vi). Blank lines, indents, and lines beginning
with '#' are ignored because of the '.nsb' file format rules.
-cvsExclude
When creating a '.nsb' file from a '.npd' file, automatically
ignore files in the same way CVS and rsync --cvs-exclude do.
Unless an "excludePaths" also excludes .cvsignore files, they will
be read for additional patterns to exclude for that current direc-
tory and all subsequent directories.
-ignoreSecurity
Ignore PGP signature when processing a '.nsb' file. WARNING: Use
carefully, only when you can trust the source of the '.nsb' file.
This must be before the -update or -poll option on the command
line.
-getPathPackages
List package(s) that contain the given installed paths. The paths
must be complete paths: that is, the package "installTop" combined
with the relative paths inside the packages. The installTop part
of the pattern is before % substitutions. Note that the installTop
part can be the empty string if installTop itself is empty, thus
making all the patterns appear as relative paths. As an optimiza-
tion, if there is only one matching registered package or if the
path exactly matches a registered validPath (that is, a validPath
without glob wildcards), the package is listed without checking to
see if there is actually an installed path that matches one of the
expressions. The package names are printed on stdout.
-getPathRegisteredPackages
Like -getPathPackages except that only the registry is consulted;
packages are never checked to see if a file is actually installed.
-getPackagePaths
List the installed paths for given package(s) on stdout, relative
to installTop.
a general purpose command that has very little to do with the rest
of NSBD, it is just here for convenience, especially for invoking a
remote CGI script, and because it just takes one extra line of code
to implement.
-postUrl
Send standard input as an http POST command to the given url and
send the result to standard output. POST operations require the
content length to be known up front, so that can be passed with a
postLength=N command line variable; if the variable is not set,
standard input will be copied into memory before it is sent. As
with -getUrl, this has very little to do with the operation of the
rest of NSBD.
-dumpRegistry
Write all previously loaded registry files to the the specified
output file. Files to be loaded must be specified with registry-
Files= on the command line.
-dumpConfig
Write all previously loaded config files to the the specified out-
put file. Files to be loaded must be specified with configFiles=
on the command line.
FILE FORMAT
All NSBD files have the same basic format. General format of each non-
commentary line: keyword plus colon (:) followed by whitespace followed
by value. The value may instead be indented any amount on the follow-
ing line. If there is no value, the keyword is ignored. If the value
is a list of items, the items can be comma-separated on the same line
as the keyword, or the first item may be indented on the following line
and subsequent items indented the same amount on lines after that.
Sub-keywords, if any, must be indented further on lines below a list
item. For a more detailed description see "nsbd -help fileformat".
Keywords in Not-so-bad Configuration '.ncf' file
This file contains configuration options for maintainers and users.
nsbConfiguration:
Identifies file type and version. Current version is 1.
nsbdpath:
Path to directory that NSBD uses for its support files (especially
config.ncf and registry.nrd). Can also come from environment $NSBD-
PATH or $nsbdpath. Default is ~/.nsbd. If overridden on the com-
mand line to be empty, NSBD does try to reference the files that
are normally there.
configFiles:
Paths to configuration files. If any of the paths are relative,
they are relative to the "nsbdpath" keyword (normally ~/.nsbd).
Default is "config.ncf". To override the default, this has to be
used on the command line. These are also processed inside each
automatically-generated updates are written to last file on the
list; earlier registry files are read-only.
logFile:
Path to file in which to log messages. If a relative path, it is
relative to the "nsbdpath" keyword (normally ~/.nsbd). Default is
"updates.log".
logDays:
Number of days to accumulate log messages in the logFile before
renaming it with an "old" prefix. If set to 0, will grow without
bounds and it will be the user's responsibility to truncate it.
Default 7.
logLevel:
Level of messages to put into log file. 0: errors only; 1: also
warnings; 2: also maintainer notices; 3: also file changes; 4: also
progress info; 5: also per-file fetch messages for batched fetches;
6: reserved; 7: also debug messages. Default 3.
verbose:
Message level to display interactively. 0: errors only; 1: also
warnings; 2: also maintainer notices; 3: also file changes; 4: also
progress info; 5: also per-file fetch messages for batched fetches,
and url fetch/post percent-done messages for those that take more
than three seconds; 6: also percent-done messages for all url
fetches/posts; 7: also debug messages. Default 4.
pgp:
Pathname for the PGP or compatible program, required if signatures
are used. It is highly recommended to use a complete path to the
program for security reasons. If using PGP 5 or similar where the
program is split into parts, specify the pgpv program; the corre-
sponding pgpk and pgps programs must be in the same directory.
Command line options can also be included here; for example, NSBD
assumes the language that PGP reports in is English, so if the
default is set to another language you could add '+language=en'
here.
pgpVariant:
Variant of PGP that is referred to in the 'pgp' keyword. Supported
types are:
1. "pgp": works with at least pgp 2.6.2 and pgp 4.0.
2. "pgp5": works with at least pgp 5.0.
3. "gpg": works with gpg (the GNU Privacy Guard).
Default is calculated from the 'pgp' keyword: if the first word of
that keyword ends in "gpg" (where words are separated by whites-
pace), the variant is assumed to be "gpg"; if it ends in "pgpv",
the variant is assumed to be "pgp5"; otherwise the variant is
assumed to be "pgp".
age specifies both an rsync topUrl and a http multigetUrl, rsync will only
be used if this keyword is explicitly set.
breloc:
Pathname for the breloc program, used for binary relocates by the "reloc-
Top" keyword. Default is 'breloc -r'.
http_proxy:
URL (of form "http://proxyhost[:portno][/]") of HTTP proxy server, if any.
Default portno is 8080. If not set here, default is from environment
$HTTP_PROXY or $http_proxy.
ftp_proxy:
URL (of form "http://proxyhost[:portno][/]") of HTTP proxy server that can
serve ftp URLs. Ftp is only currently supported through the http server.
Default portno is 8080. If not set here, default is from environment
$FTP_PROXY or $ftp_proxy.
no_proxy:
List of IP domains for which HTTP proxies should not be used. If not set
here, default is from environment $NO_PROXY or $no_proxy.
proxyAuthorization:
Authorization to use for the http proxy in the form of username:password.
Note that if this needs to be at all secure you should protect your con-
figuration file from being read by other people.
httpUserAgent:
User-Agent value to put in HTTP headers.
tmp:
Directory in which to put small scratch files, usually a RAM disk. If not
set here, default is from environment $TMP or $tmp, or else /tmp.
installTmp:
Directory in which to temporarily store files until all files in an update
are successfully retrieved. For best performance, should be in the same
filesystem as all the packages are installed in. If there is a failure
during retrieval, the temporary files will remain there so they can be
used on a subsequent attempt. If a relative path, it is relative to the
per-package installTop. Default is ".nsbdtmp".
createMask:
File creation mask to use on new files. This is the Unix umask, in octal.
Note that the permissions that are distributed with files in NSBD packages
only indicate "rwx", that is, read, write and execute; those will apply to
all protection levels (user, group, and other) unless masked by this key.
Default is 022.
pathPerms:
List of paths and corresponding file permissions to use for those paths
(after substitutions) in Unix-style octal. This list is applied after any
per-package pathPerms in the registry database. Each list item is a Unix
"glob" style expression ("*", "?", or "[]" wildcards) followed by whites-
Paths that do not match any glob expression here will use the default
permissions.
generatedIndentLength:
Indentation length used for each level on generated files, range 1-8,
default 4. Each 8 spaces of ident is replaced by a tab.
termCommand:
Command that is able to execute commands in a window that prompt the user,
for the rare cases when that is needed. Must accept a "-T" option for the
window title and a "-e" option for the command to execute. Default is
xterm.
mdType:
Message digest (secure hashing) algorithm to use when generating '.nsb'
files. Supported types are "md5" and "sha1". Default is sha1. Sha1 is
generally recognized as being more secure than md5, but it takes about
twice the compute time to check. Either algorithm will be accepted when
reading '.nsb' files, regardless of the setting of this keyword.
maintainers:
Default PGP identifiers of the maintainers of '.nsb' files that are cre-
ated. These should normally be the names and email addresses of the main-
tainers in the format "First Last (Comment) <email@domain>". If a PGP
variant is being used that reports the key ID on valid signatures, such as
gpg or pgp 5.0, the identifier may instead be specified beginning with 0x
followed by the hexadecimal key id (the letters A-F must be capitalized).
pgpKeyUrl:
Default URL at which the PGP public key of the maintainer can be
found, if not already known by the user. The ID for the key must
exactly match the given maintainer identifier.
executableTypes:
List of default supported executable types when installing files; that is
names that describe a processor plus operating system that can execute
files in the package. This can be overridden on a per-package basis in
the registration database. It is suggested to use the value reported by
GNU autoconf's "config.guess" script without any operating system version:
a triple of processor type, vendor, and operating system name separated by
dashes (for example, sparc-sun-solaris). At a minimum, they need to be
agreed upon between maintainers and users of packages if the users want to
support multiple types. If this is not set here or in the registration
database, any executableType will be accepted. Note: this default is not
used for creating '.nsb' files although the subkeyword "extension" is used
then.
aliases:
Alternate names accepted for this executable type. May use "glob"
style wildcards ("*", "?", and "[]"). If you want to choose a short
local name for executableTypes you would list the short name as the
main type and the long name as an alias. For example,
executableTypes:
solaris
Newest supported operating system version for this executable type, in
the same format as the "version" keyword as described in the Not-So-
Bad Package Description files. Larger numbers of "minOSVersion" in
installed packages will not be accepted because they will not run.
minOSVersion:
Oldest supported operating system version for this executable type.
Smaller numbers of "maxOSVersion" in installed packages will not be
accepted because they will not run. Note that this is rare, since
operating systems are usually upward compatible, (notable exception:
Unix System V Release 4.0).
installTop:
Default top level directory to install packages into. If a relative path,
it is relative to the directory from which NSBD is run. May contain %P,
%V, or %E which are replaced by the package name, the version number, or
the executableType respectively. The "installTop" directory must already
exist; it will not be created. Default is relocTop if set, otherwise
~/nsbd. Note: this is not used when creating '.nsb' files.
relocTop:
Default top level directory to relocate package files to: all occurrences
of the string specified by "installTop" in the packages' '.nsb' files are
replaced by this value, with differences in length padded by extra
slashes. If a relative path, it is relative to the directory from which
NSBD is run. May contain %P, %V, or %E which are replaced by the package
name, the version number, or the executableType respectively.
nsbStorePath:
Default path in which to store '.nsb' files when installing packages. If
a relative path, it is relative to "installTop" (and may include ".." com-
ponents). May contain %P, %V, or %E which are replaced by the package
name, the version number, or the executableType respectively. If the nsb-
StorePath value is a directory, the default filename component is
"%P.nsb". Specifying the filename component as "%P%V.nsb" (or including
%V in installTop and making nsbStorePath relative to installTop) is a good
way to keep multiple versions of a package installed. Default is the
value of nsbdpath.
pathSubs:
List of additional substitutions to perform on "paths" when they are
installed. These are used when installing packages that were described in
'.nsb' files, after the substitutions that were passed in the file and
after any per-package substitutions. Note: this value is not used when
creating '.nsb' files. See the description of this keyword in package
description files for more details on the content.
regSubs:
List of additional regular expression substitutions to perform on "paths"
when they are installed, after applying "pathSubs". Note: this value is
not used when creating '.nsb' files. See the description of this keyword
in package description files for more details on the content.
backupSubs:
'.nsb' files. Note that some of these keys give a lot of power to the
maintainers, but the values that you choose depend on how much you trust
the maintainers. Supported keys are these, with the associated conditions
that must be true in order for the change to be allowed:
1. nsbUrl - '.nsb' file(s) at new nsbUrl must be identical to the one
that does the update.
2. maintainers (NOT IMPLEMENTED YET) - all PGP keys must either already
exist in the user's PGP public key ring or the keys at the pgpKeyUrl
must be sufficiently certified to satisfy PGP.
3. validPaths - all paths in the package must not conflict with any other
paths of previously installed packages under the same installTop.
4. preUpdateCommands - unconditional.
5. postUpdateCommands - unconditional.
Unrecognized keywords are ignored. Default is "nsbUrl". Note that to
disallow all keywords, you will need to put some unrecognized value here
(such as "none") because empty lists are completely ignored.
checkPathConflicts:
Indicates the kinds of inter-package path conflict-checking to do. Value
should be one of
1. installs - make it an error to install paths that already exist in
another package.
2. deletes - do not delete paths that also exist in another package.
3. all - do both "installs" and "deletes".
4. none - do neither.
Default is "all".
auditOptions:
List of extra jobs for the -audit option. By default -audit only identi-
fies the files and directories that are listed in stored '.nsb' files
(after applying substitutions) but do not exist or are not of the right
length. The list can include any of the following:
1. checksig - check PGP signature on the stored '.nsb' files.
2. checksums - calculate the checksums for existing files and identify
those that do not match.
3. extra - identify files that are under directories in the registered
"validPaths" of selected packages but not referred to in any stored
'.nsb' file. If the packages were selected by "all", identify all
extra files under the "installTop"(s) of the packages. Paths that are
eliminated by pathSubs or regSubs in a config file or on the command
6. update - do -update on packages that have missing files or files that
have been identified to be incorrect, making sure those files get
reloaded. If the package happens to have changed by the maintainer
since the last update, those changes will also be installed. Implies
"repair".
A maximum audit can be performed with "checksig,checksums,delete,update".
minPollPeriod:
Default minimum period to poll for changes to '.nsb' files. Value is an
integer followed by a letter (upper or lower case) 'm', 'h', 'd', or 'w'
for minutes, hours, days, or weeks respectively. If the integer is 0, no
polling is done. Default is 1d. Note that this still requires that NSBD
be invoked periodically with the '-poll' option, for example from cron.
If it is invoked only once per day, for example, it won't make much sense
to set values here of small numbers of minutes or hours. To allow for
slight differences in run time, 2 percent will be subtracted from the
specified value.
preUpdateCommands:
List of additional commands to run just before every package is about to
be updated, after any per-package "preUpdateCommands". The commands will
be given a parameter that is the name of a file that will contain relevant
information from the '.nsb' file, with a few differences; see the descrip-
tion of the same keyword in the '.nsb' file for details on the differ-
ences. If any of the commands return a non-normal exit code, the update
will be aborted. If a command begins with the special character '@', its
output will not be logged, otherwise output is logged at level 3. Note:
this is not used when creating '.nsb' files.
postUpdateCommands:
List of additional commands to run just after every package has been
updated, after any per-package "postUpdateCommands". The commands will be
passed all of the same information as the "preUpdateCommands" except for
"temporaryTop". If a command begins with the special character '@', its
output will not be logged, otherwise output is logged at level 3. Note:
this is not used when creating '.nsb' files.
pathPreserveMtimes:
Default list of paths on the maintainer side for which modification times
can be preserved. Each list item is a Unix "glob" style expression ("*",
"?", or "[]" wildcards). If this is not specified here or in the package
'.npd' file (or on the command line), no modification times will be pre-
served.
preserves:
List of optional file attributes to preserve on the user side, which is
currently only this one attribute:
mtimes - preserve the modification times that were included by the
maintainer's "pathPreserveMtimes" keyword.
Default is "mtimes"; to not preserve, set this to "none".
Keywords in Not-so-bad Registry Database '.nrd' file
packages:
List of registered package names.
distributedPackageName:
The name of the package as distributed by the maintainer. This
allows the user to register the package under a different name.
Defaults to the name the package is registered under.
maintainers:
List of identifiers for the PGP public keys that are authorized
to update the package. These must be the complete, primary PGP
user IDs listed in public keys in the PGP public key ring. If
missing, will require -ignoreSecurity command line flag to
install.
executableTypes:
List of executable types accepted for this package; that is,
names that describe a processor plus operating system that can
execute the package. Should match names used in "executable-
Types" configuration keyword, if there, or one of the exe-
cutableTypes "aliases" listed in the configuration file. If
this keyword is missing here any type in the "executableTypes"
configuration keyword will be accepted. If the "nsbUrl" con-
tains a %E, this value will be used in place of the %E (unless
overridden on the command line) so it may not be missing in
that case.
versions:
Automatically generated list of versions that are installed for
this package. Unlike "executableTypes", this is not a filter
of acceptable versions; any version is always accepted. Note
that if the '.nsb' files for different versions are stored in
different places because of a %V in "nsbStorePath" (or
"installTop" if "nsbStorePath" is relative to that), then old
versions will need to be manually removed by the user (or if a
maintainer re-releases an old version with an empty list of
paths it will also be removed).
installTop:
Top level directory to install package into. If a relative
path, it is relative to "installTop" in the configuration file.
May contain %P, %V, or %E which are replaced by the package
name, the version number, or the executableType respectively.
The installTop directory must already exist before it is used;
it will not be created. Defaults to "relocTop" if set, other-
wise defaults to the value of "installTop" in the configuration
file.
relocTop:
Top level directory to relocate package files to: all occur-
rences of the string specified by "installTop" in the packages'
'.nsb' files are replaced by this value, with differences in
length padded by extra slashes. If a relative path, it is rel-
ative to "relocTop" in the configuration file. May contain %P,
List of additional substitutions to perform on "paths" when
they are installed. These are used when installing packages
that were described in '.nsb' files, after the substitutions
that were passed in the file. See the description of this key-
word in Not-So-Bad Package Description files for more details
on the content.
regSubs:
List of additional regular expression substitutions to perform
on "paths" when they are installed, after applying "pathSubs".
See the description of this keyword in package description
files for more details on the content.
backupSubs:
List of backup substitutions to perform. These are applied
after "pathSubs" and "regSubs". The format is exactly the same
as regSubs except that the only % substitution is %P, and the
substitutions are for determining the paths in which to save
previously installed files when new versions are installed.
Any paths that match the regular expression in the first part
will be backed up using the substitution in the second part.
The substituted path must be within the validPaths of the pack-
age. Default for a package called "nsbd" is "bin/nsbd$
lib/nsbd/oldnsbd".
validPaths:
List of valid paths relative to the top level directory, after
substitutions. Unix-style file wildcards ("*", "?", or "[]")
may be included, and a %X may be used for the "executableTypes
extension". If a path ends in "/", all paths below that direc-
tory are allowed. The default is no paths are valid; to allow
all paths, use "*". Note that this may not necessarily improve
overall security if executables are distributed and then exe-
cuted; those executables will then have complete access that
the user who runs them has. However, these can help security
if, for example, distribution is done with a user id that is
more trusted than the one used for execution. They also pre-
vent accidental overwrites and assist audits.
pathPerms:
List of paths and corresponding file permissions to use for
those paths (after substitutions) in Unix-style octal. Addi-
tional items can be added in the same keyword in the configura-
tion file; see the description there for more details on the
content.
pathGroups:
List of paths and corresponding groups to use for those paths
(after substitutions). Each list item is a Unix "glob" style
expression ("*", "?", or "[]" wildcards) followed by whitespace
followed by the group to use when installing a file or direc-
tory whose path matches the expression. The user id that NSBD
is running under must have the permission to change files to
that group, which usually means the user id must be a member of
minPollPeriod:
Minimum period to poll for changes to '.nsb' files. Value is
an integer followed by a letter (upper or lower case) 'm', 'h',
'd', or 'w' for minutes, hours, days, or weeks respectively.
If the integer is 0, no polling is done. Defaults to value in
configuration file or 1d. Note that this still requires that
NSBD be invoked periodically with the '-poll' option, for exam-
ple from cron. If it is invoked only once per day, for exam-
ple, it won't make much sense to set values here of small num-
bers of minutes or hours. To allow for slight differences in
run time, 2 percent will be subtracted from the specified
value.
lastTimePolled:
Automatically generated time of when the package was last
polled successfully (with no errors), in the preferred HTTP/1.0
format.
lastServerPollTime:
Automatically generated server time of when the package was
last polled successfully, in the preferred HTTP/1.0 format.
This is saved separately from lastTimePolled because time on
the server may differ from time on the client.
preUpdateCommands:
List of commands to run just before a package is about to be
updated. Additional commands may be specified in configuration
file. The commands will be given a parameter that is the name
of a file that will contain all relevant information from the
'.nsb' file, with a few differences; see the description of the
same keyword in the '.nsb' file for details on the differences.
If any of the commands return a non-normal exit code, the
update will be aborted. If a command begins with the special
character '@', its output will not be logged, otherwise output
is logged at level 3.
postUpdateCommands:
List of commands to run just after a package has been updated.
The commands will be passed all the same information as the
"preUpdateCommands" except for the "temporaryTop" field. Addi-
tional commands may be specified in configuration file. If a
command begins with the special character '@', its output will
not be logged, otherwise output is logged at level 3.
Keywords in Not-so-bad Package Description '.npd' file
This file contains a description of the source of a package for gener-
ating a '.nsb' file.
nsbPackageDescription:
Identifies file type and version. Current version is 1.
version will be replaced by dashes. If there is no version speci-
fied, the "generatedAt" field will be used as a version for many
purposes.
summary:
One-line description of the package.
description:
Multi-line description of the package.
releaseNote:
Multi-line release note, displayed as an informational message when
package is installed.
maintainers:
PGP user identifiers of the maintainers of the package. These
should also be the names and email addresses of the maintainers in
the format "First Last (Comment) <email@domain>".
pgpKeyUrl:
URL at which the PGP public key of the maintainer can be found,
if not already known by the user. The primary user ID for the
key must exactly match the given maintainer identifier.
updateParameters:
Parameters that are defined by preUpdateCommands or postUpdateCommands.
These are simply passed through to the file that those commands see.
executableTypes:
Executable types supported in this package if it contains executables;
that is, names that describe a processor plus operating system that can
execute programs in the package. It is suggested to use the value
reported by GNU autoconf's "config.guess" script without any operating
system version: a triple of processor type, vendor, and operating system
name separated by dashes (e.g. sparc-sun-solaris). At a minimum, they
need to be agreed upon between maintainers and users of packages if the
users want to support multiple types.
minOSVersion:
Minimum version number of the operating system that the package works
on for this executableType, in the same number format as the "version"
keyword.
maxOSVersion:
Maximum version number of the operating sytem that the package works
on for this executableType. Note that this is rare, since operating
systems are usually upward compatible (notable exception: Unix System
V Release 4.0).
requiredPackages:
List of other NSBD-compliant package names that are required by this pack-
age.
minVersion:
generated, in the same format as the "generatedAt" field. The time,
day of week, and/or timezone may be ommitted leaving just a date.
nsbUrl:
URL of a '.nsb' file for required package. If omitted and the user
does not already have the required package, the user will only see a
warning but then installation will proceed. May contain %P, %V, or %E
which will be replaced by the required package name, the required
package minVersion, or the executableType respectively.
minPollPeriod:
Minimum poll period to suggest to the user. Value is an integer followed
by a letter (upper or lower case) 'm', 'h', 'd', or 'w' for minutes,
hours, days, or weeks respectively. If the integer is 0, no polling is
done. Default is to use user's default.
installTop:
Top level install directory to suggest to the user. If a relative path,
relative to the user's default installTop. May begin with a tilde (~)
indicating the user's home directory. May contain %P, %V, or %E which are
replaced by the package name, the version number, or the executableType
respectively. Also used to determine which path to relocate when the user
sets "relocTop": if the package has compiled-in paths, it is a good idea
to set the "prefix" to have a large number of extra trailing slashes (I
suggest a total of 64 bytes) to allow the user flexibility in choosing a
path to relocate to; the extra slashes do not need to be specified here,
however.
preUpdateCommands:
Command list to suggest to the user to run just before this package is
about to be updated. The commands will be given a parameter that is the
name of a file that will contain relevant information from the '.nsb'
file, with these differences:
1. The beginning keyword will be "nsbUpdate" instead of "nsbFile".
2. There will be an extra keyword "temporaryTop" that is the name of the
directory that contains the new versions of changing files.
3. The "installTop" keyword will be there after substitutions.
4. "maintainers" will contain the PGP user id of the package signer.
5. "paths" will contain only those files that are changing, after substi-
tutions have been applied and without subkeywords.
6. An extra keyword "removePaths" will list files to be removed.
If any of the commands return a non-normal exit code, the update will be
aborted.
postUpdateCommands:
Command list to suggest to the user to run just after this package has
been updated. The commands will be passed all of the same information as
installation of the '.nsb' file (unless the user has set up manual inter-
vention).
topUrl:
Uniform Resource Locator (URL) for the base of all files listed under the
"paths" keyword. The protocols http:, ftp:, and rsync: are supported.
May contain %P, %V, or %E which are replaced by the package name, the ver-
sion, or the first executable type listed in executableTypes respectively.
May instead (or in addition) have a "multigetUrl" keyword.
multigetUrl:
Uniform Resource Locator (URL) for a program, such as a CGI script that
uses nsbd -multigetFiles or -multigetPackage, that is able to retrieve
multiple files on a single http connection using the "NSBD multiget proto-
col" for improved performance over having a separate http connection per
file. May contain %P, %V, or %E which are replaced by the package name,
the version, or the first executable type listed in executableTypes
respectively.
pathSubs:
List of substitutions to perform on "paths" when they are installed. Each
list item has two parts separated by whitespace: the first part is the
part to match and the second part is the part to substitute. The second
part can be missing if the match part is to be deleted (and if the match
part matched the whole path the file will not be installed at all). The
match part may contain "glob" style wildcards ("*", "?", and "[]"). The
match is made from the beginning of the path to the end of directories;
for example, lib/tcl will not match lib/tcl7.5 but will match the first
two components of lib/tcl/libtcl.a. The match part may contain %E to
match any of the "executableTypes", %V to match the "version", or %P to
match the package name. If the match part contains %E, paths that match
non-applicable executableTypes will not installed. For example, a path of
"bin/prog.%E" and a pathSub of "bin/prog.%E bin/prog" is a good way to
include multiple executable types in the same package but only install
one.
regSubs:
List of regular expression substitutions to be performed on "paths" when
they are installed after applying "pathSubs". Each list item has two
parts separated by whitespace: the first part is a regular expression like
that of the Unix "egrep" program and the second part is the substitution.
The substitution can contain & to include the pattern matched or 0 where n
is a decimal number, to include the n'th parenthesized subexpression. The
substitution can be empty if the matched expression is to be deleted (and
if the match part matched the whole path the file will not be installed at
all). The results of the substitution must be strictly below the top
directory. The match part may contain %E to match any of the "executable-
Types", %V to match the "version", or %P to match the package name. If
the match part contains %E, paths that match non-applicable executable-
Types will not be installed. For example, having paths ending in ".%E"
and having a regSub of ".%E$" is a good way to include multiple executable
types in the same package but only install one.
urlPresubstitutions:
Suggested list of valid paths, if the default calculated from "paths" is
not sufficient. Valid paths are relative to the top level directory,
after substitutions. Unix-style file wildcards ("glob" style "*", "?", or
"[]") may be included. If a path ends in "/" here, all paths below that
directory are valid. To reserve all paths under the top level directory,
use "*".
localTop:
Path of the local base directory of the "paths" keyword to use when creat-
ing '.nsb' files. This is relative to the directory that NSBD is run
from, or a complete pathname. Defaults to ".".
paths:
List of pathnames relative to "localTop" to include in the package, unless
excluded by the "excludePaths" keyword. No pathname may include ".."
components or start with "/" or "~" (that is, they must be strictly under
the top level). If the pathname refers to a directory, all files below
that directory will be included recursively. May use Unix "glob" style
file wildcards ("*", "?", or "[]"). A %E will match all "executable-
Types", and a %V will match the "version". If a %E is present, a %X may
also be present to substitute the value defined by "executableTypes exten-
sion". If a file is a relative symbolic link to a file that is under the
top level of the package, the pathname will be included in the package as
a link rather than as the file it refers to. IMPORTANT NOTE: the paths
that are found by the list here are also used as the basis (after substi-
tutions) of the default suggested "validPaths" when someone registers for
your package, unless you explicitly include the validPaths keyword. Most
significantly, if you want to reserve an entire directory for future addi-
tions to your package, you should include the entire directory here or
manually set "validPaths."
excludePaths:
List of paths to exclude from the "paths" list. May contain Unix "glob"
style wildcards ("*", "?", or "[]").
pathModes:
List of paths (before substitutions) and corresponding file permission
modes. Each list item is a Unix "glob" style expression ("*", "?", or
"[]" wildcards) followed by whitespace followed by the file permission
mode to use when installing the file. The expression may contain %E which
will match all "executableTypes" or %V which will match the "version".
The mode may contain any of "r", "w", or "x" in any order for readable,
writable, and executable. The order of the expressions is significant:
the first expression that matches a path, if any, is the one that will
apply. For example, if the first list item is "*bin/* rwx" and the second
item is "* rw", then any file in a bin directory will get a mode of "rwx"
and every other file will get a mode of "rw". Paths that do not match any
glob expression here will use the mode of the original file.
pathPreserveMtimes:
List of paths for which modification times can be preserved. Each list
item is a Unix "glob" style expression ("*", "?", or "[]" wildcards). If
this is not specified here or in the configuration file (or on the command
line), no modification times will be preserved.
generatedAt:
Time at which this file was created in the preferred HTTP/1.0 for-
mat; for example, "Sun, 06 Nov 1994 08:49:37 GMT".
package:
Name for the package. The package name will be used for the file-
name of the '.nsb' file, so it must be short and made up of only
alphanumeric characters or the characters '!', '_', '.', '+', or
'-'.
version:
Same as in Not-so-bad Package Description '.npd' file.
summary:
Same as in Not-so-bad Package Description '.npd' file.
description:
Same as in Not-so-bad Package Description '.npd' file.
releaseNote:
Same as in Not-so-bad Package Description '.npd' file.
maintainers:
Same as in Not-so-bad Package Description '.npd' file.
pgpKeyUrl:
Same as in Not-so-bad Package Description '.npd' file.
updateParameters:
Same as in Not-so-bad Package Description '.npd' file.
executableTypes:
Same as in Not-so-bad Package Description '.npd' file.
minOSVersion:
Same as in Not-so-bad Package Description '.npd' file.
maxOSVersion:
Same as in Not-so-bad Package Description '.npd' file.
requiredPackages:
Same as in Not-so-bad Package Description '.npd' file.
minVersion:
Same as in Not-so-bad Package Description '.npd' file.
minGeneratedAt:
Same as in Not-so-bad Package Description '.npd' file.
maxVersion:
Same as in Not-so-bad Package Description '.npd' file.
maxGeneratedAt:
Same as in Not-so-bad Package Description '.npd' file.
postUpdateCommands:
Same as in Not-so-bad Package Description '.npd' file.
nsbUrl:
Same as in Not-so-bad Package Description '.npd' file.
topUrl:
Same as in Not-so-bad Package Description '.npd' file.
multigetUrl:
Same as in Not-so-bad Package Description '.npd' file.
pathSubs:
Same as in Not-so-bad Package Description '.npd' file.
regSubs:
Same as in Not-so-bad Package Description '.npd' file.
urlPresubstitutions:
Same as in Not-so-bad Package Description '.npd' file.
validPaths:
Same as in Not-so-bad Package Description '.npd' file.
paths:
List of relative pathnames in the package. No pathname may include ".."
components or start with a "/" or "~". Components of pathnames are sepa-
rated by "/" even on PCs. Pathnames ending in "/" indicate a directory.
linkTo:
Pathname relative to top (below it) that the path is symbolically
linked to.
hardLinkTo:
Pathname relative to top (below it) that the path is hard-linked to.
length:
Length of file at the path in bytes, maximum 2^31-1. Not present for
directories or links.
md5:
32-byte hexadecimal (ASCII characters 0-9 and a-f) md5 message digest
(checksum) of the file at path. Not present for directories or links.
sha1:
40-byte hexadecimal (ASCII characters 0-9 and a-f) sha1 message digest
(secure hash, checksum) of the file at path. Not present for directo-
ries or links.
mode:
Permission modes of the file. May contain any of "r", "w", or "x" in
any order for readable, writable, and executable. Default is "rw".
Not present for directories or links.
maintainers:
Lucent Central Exptools Administrator <exptools@lucent.com>
pgpKeyUrl: http://www.bell-labs.com/project/wwexptools/keys/exptools.txt
executableTypes: sparc-sun-solaris,mips-sgi-irix
nsbUrl: http://www.bell-labs.com/project/nsbd/%P.nsb
topUrl: http://www.bell-labs.com/project/nsbd/binaries
regSubs:
# delete all .%E suffixes when installing
.%E$
paths:
# %E expands to every executableType
bin/nsbd.%E
lib/nsbd/
man/man1/nsbd.1
To update the file to include complete comments for each available key-
word:
nsbd -updateComments nsbd.npd
To create the '.nsb' file from the package description:
nsbd nsbd.npd
To register for the package via a GUI:
nsbd -register http://www.bell-labs.com/project/nsbd/%P.nsb
To poll for and install updates for all packages, good to do from cron
nightly or weekly:
nsbd -poll all
To manually register for the nsbd solaris binary package, add this to
~/.nsbd/registry.nrd:
packages:
nsbd
nsbUrl:
http://www.bell-labs.com/project/nsbd/nsbd.nsb
maintainers:
Lucent Central Exptools Administrator <exptools@lucent.com>
executableTypes:
sparc-sun-solaris
validPaths:
bin/nsbd
lib/nsbd/
man/man1/nsbd.1
To automatically make and install after an update to nsbd source, add
this to ~/.nsbd/registry.nrd:
packages:
nsbdsrc
postUpdateCommands:
cd ~/src/nsbd/unix;configure --prefix ~/nsbd;make install #
The ending '#' is to ignore the parameter of the name of a file con-
taining a description of the update.
VERSION
Man(1) output converted with
man2html