Daylight v4.9
Release Date: 1 February 2008

Name

thorfilters - Filter programs for Thor/Merlin management

Unix Synopsis

thorfilters - "filter" programs for Thor/Merlin management

Description

"Thorfilters" is a set of programs that perform Thor/Merlin database-management tasks. Their capabilities are similar to those provided by sthorman, however, some tasks are better done with sthorman and some with thorfilters programs.

The title "thorfilters" is from the UNIX tradition of "filter" programs (such as sed(1), grep(1) and sort(1)), each of which performs a single text- processing task. UNIX filter programs are treated as "building blocks", and are typically "piped together" to perform complex tasks.

This building-block approach is the basis for thorfilters. Each of these programs performs one task, such as creating a database (thormake), loading data into a database (thorload), or listing available databases (thorls). By combining these building blocks, you can perform complex Thor- and Merlin-database management tasks.

Below is a very brief summary of each thorfilter. The following "chapters" describe each "filter" in detail.

dayevict ...... evict a user from Thor or Merlin
daymessage .... send message to Thor or Merlin users
tdtcat ........ read and write Thor Data Trees (TDTs)
thorchange .... change a database's configuration
thorcrunch .... recover unused space in a Thor database
thordbping .... verify the existence of a Thor database
thordelete .... delete TDTs from a Thor database
thordestroy ... destroy a Thor database
thordiff ...... compare TDTs in two databases; print differences
thordump ...... directly dump the contents of a THOR database
thorlist ...... dump the contents of a Thor database to a TDT file
thorload ...... load data into a Thor database
thorlookup .... look up a TDT in a Thor database
thorls ........ ask a Thor server to list its databases
thormake ...... create a Thor database and/or set its properties
thorping ...... verify the existence of a Thor server
thorwho ....... ask a Thor server to list current users
merlindbping .. verify the existence of a Merlin database
merlinload .... load a database into the Merlin server's memory
merlinls ...... ask a Merlin server to list its databases
merlinping .... verify the existence of a Merlin server
merlinwho ..... ask a Merlin server to list current users
All thorfilters programs (and most other Daylight programs that use Thor and Merlin databases) use a single syntax for naming servers and databases.

The complete syntax is in database(5). Briefly, it is like this:

database%dbpass@host:service:user%userpass
Where:
database ... name of the database being opened
dbpass ..... password for the database
host ....... computer on which the server is running
service .... IPC service (or "port") the server is using
user ....... user name for logging into server
userpass ... password for "user" for logging into server
Most of the fields in the specification are optional; defaults are automatically supplied for those that you leave out.

If the database does not include passwords for the server and/or the database, you are prompted for them. If a database and/or server doesn't require a password, you indicate this by putting in the % with no password after it. For example:

mydb@zeus ...... Ask for the database and server password
mydb%@zeus% .... Blank database and server password
mydb%@zeus ..... Blank database password, ask for server password
Note that you will be prompted for passwords even if you redirect input and output -- the Thorfilters programs use a special file to prompt you that goes to your terminal even when I/O is redirected to pipes or files. (See the option SECURE_PASSWORDS, below.)

Options

There following options are common to all thorfilter programs:

-SECURE_PASSWORDS TRUE|FALSE

Normally, if passwords are entered on the command line (e.g. "mydb%mypass"), a thorfilter program will exit immediately. This is to discourage password discovery via programs, such as ps(1), that show the complete command line used to invoke a program. If SECURE_PASSWORDS is set to FALSE, passwords can be entered on the command line. See the Help Widget's "databasename" topic for more details.
-THOR_IPC_SERVICE service
-MERLIN_IPC_SERVICE service
Names the default service (see /etc/services) or "port" of the Thor server or Merlin server, respectively. Defaults are "thor" "merlin" for Thor and Merlin programs, respectively. Note that these options are ignored if a server's name includes the service (e.g. "crawdad:thor2").
-SERVER_TIMEOUT nnn
Sets a timeout value in seconds for any connection attempts. After 'nnn' seconds, all connection attempts time out and fail with a message. This prevents programs from blocking indefinitely under some circumstances. The default value is 60 seconds.

Return Value

All thorfilter programs return zero to the environment if they succeed and one if they fail. In addition, the following messages may be printed on standard error:

ERROR: can't find database "dbname"

The server couldn't find the named database. If the database was a simple filename, then it wasn't in the server's search path (see thorserver(1) and sthorman(1)). If the database name was a complete path (file plus directory), then that database does not exist.

ERROR: Can't connect to host: crawdad (dy_ipc_connect)
The specified server couldn't be reached. Either it is not running, is using a different service, or is not reachable via your network.
ERROR: login failed - invalid user/password or host (ipc_login)
The username/password you used are not correct, or the server is using the "restricted hosts" mode of security (see sthorman) and your computer is not on the list of authorized computers.
One or more of the options files couldn't be read. Usually due to an incorrect definition of the environment variables DY_ROOT or DY_OPTIONS.
SECURE_PASSWORDS is TRUE ... server%password specification not allowed
You entered a password on the command line without setting the option SECURE_PASSWORDS to FALSE.

Related Topics

dayevict(1) daymessage(1) merlindbping(1) merlinload(1) merlinls(1) merlinping(1) merlinwho(1) thorchange(1) thorcrunch(1) thordbping(1) thordelete(1) thordestroy(1) thordiff(1) thordump(1) thorlist(1) thorload(1) thorlookup(1) thorls(1) thormake(1) thorping(1) thorwho(1)

sthorman(1) thorserver(1) merlinserver(1)

licensing(5)

Daylight Theory Manual, Daylight System Administration Manual

$DY_ROOT/contrib/src/thor - several example shell scripts for Thor database administration.