MPD process launcher

MPD is a process manager for clusters of computers running WindowsNT/2000/XP. It can run in three different modes:

A service that launches processes in the context of multiple connecting users. This is the default installation.

A service that launches processes in the context of a single user.

A command line program started manually on all the nodes. This can be useful for evaluation purposes or for users who do not have the ability to install services on their machines. This option acts like single user mode.

Quick reference

NOTE: The binary distribution of mpich.nt, mpich.nt.1.2.5.exe, installs mpd for you using the setup program. You can use Add/Remove programs to remove it. If you want to install mpd by hand, use the following information:

Default Installation - multi-user

1. Copy mpd.exe to all the nodes.
2. Logon to each node with an account that has Administrator privileges.
3. Execute mpd -install from a command prompt on each node.
4. From a single node, run mpiconfig.exe
1. Click Select to find the hosts where you installed mpd.
2. Click Add to add these hosts to the list. If you can't see all the hosts where you installed mpd, add them manually with the edit box above the list.
3. Click Set to set the global options on each machine.

5. Compile a sample application like cpi from the examples nt directory.
6. Copy cpi.exe to all the nodes or place it in a shared directory.
7. Run 'mpirun -np 4 cpi'

1. Copy mpd.exe to all the nodes.
2. Logon to each node with an account that has Administrator privileges.
3. Execute mpd -install -account domain username -getphrase on each node. Input the password of the user and a passphrase for the mpds.
4. If this user has administrator privileges, run mpiconfig.exe
1. Click Select to find the hosts where you ran mpd -install
2. Click Add to add these hosts to the list. If you can't see all the hosts where you installed mpd, add them manually with the edit box above the list.
3. Click Set to set the hosts on each machine.

5. Compile a sample application like cpi
6. Copy cpi.exe to all the nodes or place it in a shared directory.
7. Run 'mpirun -np 4 cpi'

1. Copy mpd.exe to all the nodes.
2. Execute mpd -d on each node.
3. Compile a sample application like cpi
4. Copy cpi.exe to all the nodes or place it in a shared directory.
5. Create a machine file and fill it with the host names where mpd is running.
6. Run 'mpirun -np 4 -machinefile file cpi'

1. Execute mpd -remove from each node or type ``stop'' into the window where mpd -d is running.
2. Delete all the files.

Command line options

Installation

mpd -install -regserver -interact -phrase x -getphrase -account x -password x -port x -mpduser

The options -install and -regserver are synonyms to install the service.

The option -interact allows the service to start applications with access to the desktop window. Don't use this option unless you have to show windows while your application is running.

The option -phrase x allows you to set the passphrase for mpd authentication. When a remote machine connects to the mpd, this phrase is used to encrypt a challenge response string to authenticate the remote user. The option -getphrase causes the mpd to prompt for the passphrase to be entered. This is useful if you don't want to pass the phrase on the command line. If -phrase x or -getphrase are not specified, the default passphrase is used.

The -port option allows you to specify a port for the mpd to listen on. This must be the same on all the nodes. If you do not specify this option, the default is used, 8675.

The options -account x and -password x allow the user to install the service in single user mode. In single user mode, all processes launched are placed in the security context of the specified user no matter who connects to the mpd. The advantage of this mode is that no passwords are needed again after install time. The disadvantage is that any user who knows the mpd passphrase can launch processes in the context of the installed user. If -account x is specified but -password is not, the user will be prompted to enter a password. Accounts should be specified in the form ``Domain User''.

The option -mpduser in conjunction with -install installs the mpd with the ability to accept anonymous launch requests that are launched in the context of a registered mpd user. The option enables the following mpd console commands: setmpduser, clrmpduser, enablempduser and disablempduser.

mpd -remove -unregister -uninstall

The options -remove, -unregister and -uninstall are all synonyms to un-install the service.

mpd -d -port x -phrase x -getphrase

The -d option allows a user to run an mpd from the command line. This is for debugging the mpd or for users who need to execute the mpd manually. The options -port x and -phrase x or -getphrase allow the user to specify what port to listen on and what passphrase to use. The option -getphrase will cause the mpd to prompt for a passphrase. If these options are not specified, mpd will use the default port and passphrase. While the mpd is running it will spit out information as messages pass through and commands are issued. You can enter ``stop'' to stop the mpd or ``quit'' to forcibly exit the process.

mpd -update -mpd x -host x -hostfile x -account x -password x -singleuser -port x -phrase x -getphrase

Before you upgrade a set of running mpds, make sure there are not any jobs running. The upgrade process will terminate any running processes managed by the mpds.

The -update option is used to upgrade running mpds after a new version has been downloaded. Specify the location of the new mpd.exe with the -mpd x option where x is the full path to the newly downloaded mpd.exe including the executable name (mpd.exe). If you do not specify this option, the mpd will use itself as the upgrade module. So if you do not specify -mpd, make sure you execute the new mpd and not the old mpd.

Specify the host to upgrade with the -host x option or a list of hosts to upgrade in a file with the -hostfile x option.

You need to specify a user with enough privileges to be able to stop and start services on the specified hosts with the -account x and -password x options. If you do not provide a password on the command line, you will be prompted to enter one.

The options -port x and -phrase x or -getphrase allow you to specify what port to connect to and what passphrase to use. If you specify the option -getphrase, you will be prompted to enter a passphrase. If these options are not specified, the default port and passphrase will be used.

If you do not specify any options, you will be prompted to enter a host, account, and password.

Note: You cannot upgrade mpds running from a command prompt: mpd -d. If you installed the mpds in single user mode, the user must have administrator privileges in order to upgrade this way. Use the -singleuser option instead of an account and password in this case because single user mode does not require a user logon.

You can always upgrade manually by doing the following on each node:

1. Execute mpd -stop to stop the running mpd.
2. Delete the old mpd.exe and place the new version in its place - the exact same place. The name and path of mpd.exe cannot change.
3. Execute mpd -start to start the new mpd.

If you want to move mpd.exe to a new location you will have to uninstall (mpd -r emove) and then re-install (mpd -install ...).

{mpd -console -port x -phrase x -getphrase}

{mpd -console host -port x -phrase x -getphrase}

The -console option creates a console session with an mpd on the local host or the host specified. If the mpd is listening on a port other than the default, the option -port x can be used to specify what port to connect to. If -phrase x or -getphrase are not specified the mpd searches for the passphrase specified at install time and then reverts to the default passphrase if mpd is not installed on the local host.

{mpd -start}

The option -start starts an installed mpd on the local host. Note: the mpd is started automatically at installation time.

{mpd -stop}

The option -stop stops an installed mpd on the local host. Note: when the mpd stops, it will kill all running processes that it has launched.

{mpd -restart}

The option -restart stops and restarts the mpd on the local host.

{mpd -restart host}

The option -restart host connects to 'host' and restarts the mpd on that host.

{mpd -clean}

The option -clean removes all the settings from the registry. The next time the mpd is started it will revert to the default values.

{mpd -v -version}

The options -v and -version will both print out version information.

{mpd -h -? -help}

The options -h -? or -help will print out a list of the most common command line options.

Console commands

This section describes all the commands that can be issued to a mpd in a console session. Console sessions are established by executing mpd -console or mpd -console host as described in the previous section.

DATABASE OPERATIONS

An mpd can maintain a set of in-memory databases. The databases store key/value pairs of strings. The data is not persistent, so when an mpd is taken down, all the databases are destroyed. Mpd is not a database application. This capability is provided so parallel applications can pass small amounts of initialization data between processes. It is not intended to hold user data.

dbcreate

This command creates a database and returns the name.

Return values:

The name of the database or DBS_FAIL if an error occurred.

dbcreate name or name=x

This command creates a database with the specified name. DBS_SUCCESS is returned if the database is created or if it already exists.

Return values:

DBS_SUCCESS or DBS_FAIL

dbdestroy name or name=x

This command removes an entire database.

Return values:

DBS_SUCCESS or DBS_FAIL

dbput name:key:value or name=x key=x value=x

This command inputs a key/value pair into the specified database. The key values need to be unique. It is not allowed to call dbput with the same key more than once into the same database.

Return values:

DBS_SUCCESS or DBS_FAIL

dbget name:key or name=x key=x

This command retrieves the value of the key in the specified database.

Return values:

The value of the key in the specified database or DBS_FAIL

dbdelete name:key or name=x key=x

This command deletes a key from the specified databse.

Return values:

DBS_SUCCESS or DBS_FAIL

dbfirst name or name=x

This command starts the iterator on the specified database. It returns the first key/value pair in the database or DBS_END if the database is empty.

Return values:

key=value, or DBS_END or DBS_FAIL

dbnext name or name=x

This command returns the next key/value pair in the specified database. Repeat this command until it returns DBS_END to iterate through the entire database. You must call dbfirst before this command to start the iteration.

Return values:

key=value, DBS_END, or DBS_FAIL

dbfirstdb

This command starts the iterator on the entire database namespace. It returns the name of the first database in the space or DBS_END if there are no existing databases.

Return values:

name=name or DBS_END

dbnextdb

This command returns the name of the next database in the namespace. Repeat this command until it returns DBS_END to iterate through the names of all available databases. You must call dbfirstdb before this command to start the iteration.

Return values:

name=name or DBS_END

launch h=host c=cmd e=env m=map d=dir a=account p=password 0=stdin 1=stdout 2=stderr or 12=stdouterr or 012=inouterr k=rank

With the default installation, the mpds run as services on each of the nodes. When a launch command reaches the requested node, the mpd uses the account and password parameters to launch the requested process in the security context of that user. If the mpd has been started in single user mode, then the mpd runs in the security context of a single user. The mpd runs in single user mode if it was installed with a specific username and password or if it is run from a command prompt, mpd -d .... When in single user mode all processes are launched in the security context of the same user. There is no need to pass the account and password. If they are provided they are ignored.

h=host

the hostname to launch the process on. If this option is not specified the process is launched on the local host.

c=cmd

the path to the executable plus any arguments. For example:
c=c: my favorite path myapp.exe arg1 arg2 or
c= somehost someshare some path someapp.exe arg1 arg2.

e=env

a string of environment variables to set. Single quote this list and separate values by the vertical bar character. Example: e='var1=val1|var2=val2|var3=val3'

m=map

network drive mapping option in the form: 'drive: host share'. Multiple mappings can be specified separated by semicolons.
eg. m=y: myhost myfiles;z: myhost myhome)

d=dir

the working directory to launch the process in

a=account p=password

the account and password used to set the security context for the launched process. If the mpd is in single user mode, these parameters are not necessary and they are ignored.

0=stdin 1=stdout 2=stderr 12=stdouterr 012=stdinouterr k=rank

these options specify where to connect the standard input, output, and error of the launched process. The format is host:port. For example, 012=somehost:1234, would connect to the host ``somehost'' on port 1234 three times to redirect standard input, output and error. When connecting to this host, the mpd sends a five byte message first. The first byte is a 0, 1, or a 2 to signify stdin, stdout or stderr. The next 4 bytes are the integer specified by the k=rank option. If no k option is specified a value of zero is sent by default.

Return values:

launchid

geterror launchid

This command returns the current error message for the launch command corresponding to the provided launchid. ERROR_SUCCESS signifies that the launch was successful. If the launch command is still in progress, the return value is LAUNCH_PENDING. If there is an error associated with the launch, the specific error message will be returned.

Return values:

ERROR_SUCCESS, LAUNCH_PENDING, ``specific error message''

getpid launchid

This command blocks until the process associated with launchid has been started. If there was an error in the startup of the process, this command will return -1 and geterror can be used to get the specific error message.

Return values:

process id or -1

getexitcode launchid

This command returns the exit code of the process associated with launchid. If the process is still running, ACTIVE is returned. If there was a error launching the process, FAIL will be returned and geterror can be called to retrieve the error message.

Return values:

exitcode, ACTIVE, FAIL

getexitcodewait launchid

This command blocks until the process associated with launchid exits. If there is an error and the process was not launched, FAIL will be returned and geterror can be called to retrieve the error message.

Return values:

exitcode, FAIL

freeprocess launchid

This command frees the local structures used to store the process id, exit code and state. freeprocess should be called after there is no need to get any further information about a process, usually after a successful call to one of the getexitcode commands. After this command, the launchid becomes invalid and cannot be used in any other calls.

Return values:

nothing

kill launchid

This command kills the process associated with launchid. kill launchid will only work if there is a valid process id in the local launchid structure. If the state is LAUNCH_PENDING or an error has occurred, kill will not succeed. This is important because if a launch command is issued and immediately followed by a kill command, the kill will not succeed if the state of the process is LAUNCH_PENDING. To guarantee that the process has started before trying to kill it you should call getpid first.

Return values:

nothing

kill host=x pid=x

This command attempts to kill the process on host x associated with pid x. kill can only kill processes launched by the mpd.

Return values:

nothing

killall

This command attempts to kill all the processes launched by the mpd.

Return values:

nothing

ps

This command returns a list of the active processes started by the mpd.

Return values:

pid:command line...

hosts

This command returns the hosts that the current mpd knows about.

Return value:

hostA,hostB,hostC,...

shutdown

This command stops the mpd and closes the console connection. Do not use this command unless you want to stop the mpd. You will have to run mpd -start to get the mpd to start again. Use done to close a console session.

Return values:

nothing

restart

This command restarts the mpd and closes the console connection. You will have to reconnect to the mpd. Use done to close a console session.

Return values:

Restarting mpd...

done or quit

This command closes the current console session with the mpd.

Return values:

nothing

set key=value

This command sets the key/value pair in the mpd section of the registry. For example, set temp=c: temp sets the temp directory for mpd files on all the nodes.

Return values:

nothing

get key

This command gets the value of the key provided from the mpd section of the registry.

Return values:

value

delete key

This command removes the specified key from the mpd section of the registry.

Return values:

nothing

version

This command returns the version numbers and date of the mpd the console session is connected to. For example: 1.2.3 Mar 2 2002

Return values:

release.major.minor date

mpich version

This command returns the version numbers and date of the mpich dll on the host the console session is connected to. For example: 1.2.4 Apr 12 2002

Return values:

release.major.minor date

config

This command returns all the mpd registry key/value pairs on the host local to the mpd.

Return values:

key=value...

print

This command spits out a lot of internal state useful only for debugging mpd.

Return values:

internal state

stat { param}

This command reports internal information on the specified parameter where param can be one of the following:

ps - running processes, command line, environment variables, working directory, mpich rank, io redirection

launch - launch structures, id, process id, process state

config - mpd registry settings

context - open contexts, contexts are socket connections to the mpd - both internal and external

tmp - temporary files

barrier - outstanding barriers

forwarders - forwarders open on this node, input port and output host:port

cached - cached user handles

Return values:

internal state

setdbgoutput { filename}

This command redirects the output of the running mpd to a file. This is useful for logging all the commands and operations that mpd processes and should only be used for debugging mpd.

Return values:

SUCCESS, FAIL

canceldbgoutput

This command cancels the redirection of mpd output.

Return values:

SUCCESS, FAIL

setmpduser a={ account} p={ password}

This command sets the mpd user account and password for anonymous launch requests. If you don't supply either of the two parameters you will be prompted to enter them.

Return values:

SUCCESS, FAIL - error msg

clrmpduser

This command removes the mpd user credentials and disables anonymous launch requests.

Return values:

SUCCESS, FAIL - error msg

enablempduser

This command enables anonymous launch requests.

Return values:

SUCCES, FAIL - error msg

disablempduser

This command disables anonymous launch requests.

Return values:

SUCCESS, FAIL - error msg

The file operations are for moving files between hosts, creating temporary files and one custom function for mpich.nt

fileinit account=x password=x

This command is the first command that must be issued before the other commands can be used. File operations are done under the security context of this user. If the password option is omitted, you will be prompted to input the password.

Return values:

nothing

putfile local=fullfilename remote=fullfilename replace=yes/no createdir=yes/no

This command copies the file described by the local option to the location described by the remote option. Both the local and remote options must specify complete paths including file names. The replace and createdir options refer to the remote file. replace=yes overwrites the remote file if it exists. createdir=yes causes the path described by the remote option to be created if it doesn't exist. If replace and createdir are not specified, the defaults are replace=yes and createdir=yes.

Return values:

SUCCESS or ``error message''

getfile remote=fullfilename local=fullfilename replace=yes/no createdir=yes/no

This command copies the file described by the remote option to the location described by the local option. Both the remote and local options must specify complete paths including file names. The replace and createdir options refer to the local file. replace=yes overwrites the local file if it exists. createdir=yes causes the path described by the local option to be created if it doesn't exist. If replace and createdir are not specified, the default values are replace=yes createdir=no.

Return values:

SUCCESS or ``error message''

getdir path=fullpath

This command returns the names of the folders and files found in the directory on the remote host described by the path option. The path must be a full path. The file names are returned preceded by their file size like this: 1022 cathy.txt

Return values:

folders and sizes and filenames or and error message: ERROR: error message...

createtmpfile host=x

This command creates a temporary file on the host specified and returns the file name.

Return values:

filename

deletetmpfile host=x file=x

This command deletes the file described by the file option on the host described by the host option. The file option must specify the complete path to the file.

Return values:

SUCCESS or FAIL

mpich1readint host=x file=x

This command is a custom function provided to allow mpd to launch mpich 1.2.3 applications and earlier. It reads an integer from the file that was written by the root process during MPI_Init.

Return values:

integer