6 Jun 2013
gfservice 1 Gfarm
gfservice control Gfarm servers from a remote host
`gfservice` options sub-command host-id argument ...

## DESCRIPTION

`gfservice` is an utility for Gfarm administrators to operate servers (`gfmd`, `gfsd` and PostgreSQL) on remote hosts. OpenLDAP is not supported currently. It can start, stop, set up (execute `config-gfarm` and `config-gfsd`) and clean up the servers, for example.

A sample command line of `gfservice` looks like:

    	gfservice start-gfmd gfmd2

where "start-gfmd" is a sub-command and gfmd2 is a host-id respectively. Executing the command, `gfservice` tries to start gfmd on the host named gfmd2. To specify a remote server host, `gfservice` uses host-id instead of hostname. All host-ids (gfmd1, gfmd2, and so on) are defined in a configuration file of `gfservice`. Here is an example of the configuration file:

    	gfmd1=metadb1.example.com
    	gfmd1_CONFIG_GFARM_OPTIONS="-A $LOGNAME -X"
    	gfmd2=metadb2.example.com
    	gfmd2_CONFIG_GFARM_OPTIONS="-A $LOGNAME -X"

    	gfsd1=spool1.example.com
    	gfsd2=spool2.example.com

`gfservice` determines a path of the configuration file to be read with the following procedures:

1. `-f` file option is specified, read file.

2. Otherwise, the environment variable `GFSERVICE_CONF` is defined and not empty, read the file.

3. Otherwise, read `$HOME/.gfservice`.

If `gfservice` fails to read a configuration file, it prints an error message and exits immediately. Note that the configuration file itself is a Bourne-shell script and `gfservice` includes (exactly to say, evaluates) the file. See gfservice.conf(5) for more details about the configuration file.

`gfservice` uses SSH (Secure Shell) to connect with a remote host. Since it may execute `ssh` several times during a sub-command operation, it is recommended to use an SSH agent (e.g. `ssh-agent` of OpenSSH) or an authentication key with an empty passphrase to avoid typing a passphrase every time.

In addition with SSH, `gfservice` uses Sudo to get root privilege on the remote host. Please add a line like below to `sudoers` file (Sudo's configuration file) on each remote host.

    	user ALL=(root, _gfarmfs, _gfarmmd) NOPASSWD: gfservice-agent

where user is an user name who executes `gfservice`. The NOPASSWD option is not mandatory, but `sudo` may ask you a password several times if omitted.

Since `gfservice` executes an agent command named `gfservice-agent` on the remote host using SSH and Sudo, `gfservice-agent` command must have been installed on all hosts you want to operate using `gfservice`.

`gfservice` has a plug-in system so that user can add new sub-commands. See "PLUG-IN SYSTEM" section of this man page for more details.

## OPTIONS

`-d`

  Print debug information. `gfservice` passes this option to `gfservice-agent` so that also `gfservice-agent` outputs debug information.

`-f` file

  Read configuration from file instead of the default.

`-t` time

  Set operation timeout in time seconds. When `gfservice` tries to start or stop a server program (gfmd, gfsd or a backend database), it waits until the operation is complete or time interval is elapsed. If "no" is specified as time, timeout never occurs. The default value is "no".

`-k`

  When this option is specified with sub-command `config-gfarm` or `config-gfarm-master`, `gfservice` creates a shared secret key files using `gfkey` command.

## SUB-COMMANDS FOR GFMD

The followings are sub-commands which operate `gfmd`. The given host-id argument must be "gfmdn" (gfmd1, gfmd2, ...). Otherwise `gfservice` reports an error and exits immediately.

`backend-db-status` host-id

  Exit with an exit code 0, if a backend database is currently running. Otherwise exits with 1.

`gfmd-status` host-id

  Exit with an exit code 0, if `gfmd` is currently running. Otherwise exits with 1.

`start-backend-db` host-id

  Start a backend database if it is not running currently.

`start-gfmd` host-id

  Start `gfmd` if it is not running currently.

`start-gfmd-master` host-id

  An alias of "`start-gfmd`" sub-command.

`start-gfmd-slave` host-id

  This sub-command is the same as "`start-gfmd`", but `-S` option is added to `gfmd`.

`start-gfarm` host-id

  Start a backend database and `gfmd` if they are not running currently.

`start-gfarm-master` host-id

  An alias of "`start-gfarm`" sub-command.

`start-gfarm-slave` host-id

  This sub-command is the same as "`start-gfarm`", but `-S` option is added to `gfmd`.

`stop-backend-db` host-id

  Stop a backend database if it is running currently.

`stop-gfmd` host-id

  Stop `gfmd` if it is running currently.

`stop-gfarm` host-id

  Stop `gfmd` and a backend database if they are running currently.

`kill-gfmd` host-id

  Kill `gfmd` (send SIGKILL) if it is running currently.

`restart-backend-db` host-id

  Perform "`stop-backend-db`" and "`start-backend-db`" sub-commands successively.

`restart-gfmd` host-id

  Perform "`stop-gfmd`" and "`start-gfmd`" sub-commands successively.

`restart-gfmd-master` host-id

  An alias of "`restart-gfmd`" sub-command.

`restart-gfmd-slave` host-id

  Perform "`stop-gfmd`" and "`start-gfmd-slave`" sub-commands successively.

`restart-gfarm` host-id

  Perform "`stop-gfarm`" and "`start-gfarm`" sub-commands successively.

`restart-gfarm-master` host-id

  An alias of "`restart-gfarm`" sub-command.

`restart-gfarm-slave` host-id

  Perform "`stop-gfarm`" and "`start-gfarm-slave`" sub-commands successively.

`promote` host-id

  Promote `gfmd` from a slave to a master.

`promote-gfmd` host-id

  An alias of "`promote`" sub-command.

`set-gfmd-conf` host-id directive value

  Add

      	directive value

  line to `gfmd.conf` file on the remote host. If `gfmd.conf` already has a directive line, `gfservice` deletes it and then add a new line.

`set-gfsd-conf` host-id directive value

  Add

      	directive value

  line to `gfsd.conf` file on the remote host. If `gfsd.conf` already has a directive line, `gfservice` deletes it and then add a new line.

`unset-gfmd-conf` host-id directive

  Delete a directive line in `gfmd.conf` file on the remote host. If `gfmd.conf` file doesn't contain directive line, the file is unchanged.

`unset-gfsd-conf` host-id directive

  Delete a directive line in `gfsd.conf` file on the remote host. If `gfsd.conf` file doesn't contain directive line, the file is unchanged.

`backup-backend-db`

  Backup a backend database on the remote host and output the backup data to standard out.

`backup-gfmd-conf` host-id

  Output `gfmd.conf` file on the remote host to standard out.

`backup-gfsd-conf` host-id

  Output `gfsd.conf` file on the remote host to standard out. This sub-command can be worked only when the remote host is configured in the private mode.

`backup-usermap` host-id

  Output `usermap` file on the remote host to standard out. This sub-command can be worked only when the remote host is configured in the private mode.

`restore-backend-db` host-id

  Restore a backend database on the remote host. The backup data are read from standard in.

`restore-gfmd-conf` host-id

  Recover `gfmd.conf` file on the remote host. `gfservice` reads a backup of `gfmd.conf` from standard in.

`restore-gfsd-conf` host-id

  Recover `gfsd.conf` file on the remote host. `gfservice` reads a backup of `gfsd.conf` from standard in. This sub-command can be worked only when the remote host is configured in the private mode.

`restore-usermap` host-id

  Recover `usermap` file on the remote host. `gfservice` reads a backup of `usermap` from standard in. This sub-command can be worked only when the remote host is configured in the private mode.

`config-gfarm` host-id

  Execute `config-gfarm` command on the remote host. If "gfmdn_CONFIG_GFARM_OPTIONS" variable is declared in the configuration file of `gfservice`, its value is passed to `config-gfarm` command as options. Don't use this sub-command when you want to enable replication of gfmd. Instead, use "`config-gfarm-master`" or "`config-gfarm-slave`" sub-command in that case. If `-k` option is specified, `gfservice` also creates a shared secret key files onto the gfmd host, using `gfkey` command.

`config-gfarm-master` host-id

  This sub-command is the same as `config-gfarm` but gfmd replication is enabled automatically.

`config-gfarm-slave` host-id master-host-id

  This sub-command is the same as `config-gfarm` but gfmd replication is enabled automatically and the remote gfmd host is configured as a slave of master-host-id. Then `gfservice` registers the slave host to a server list using `gfmdhost` command. `gfservice` also adds the slave host to `metadb_server_list` directive in `gfarm2.conf` file on the master gfmd host and distribute the updated `gfarm2.conf` file to all hosts defined in the configuration file. It also updates `gfsd.conf` file and distributes it to all gfmd and gfsd hosts, if "gfmdn_PRIVATE_MODE" variable is set to "true". If the value of the variable "gfmdn_AUTH_TYPE" is "sharedsecret", it also copies a shared key file from the maste gfmd to the slave gfmd host.

`unconfig-gfarm` host-id

  Execute "`stop-gfarm`" sub-command and then delete all files and directories created by gfmd and a backend database. If you want to unconfigure a slave gfmd, use "`unconfig-gfarm-slave`" sub-command instead.

`unconfig-gfarm-master` host-id

  An alias of "`unconfig-gfarm`" sub-command.

`unconfig-gfarm-slave` host-id master-host-id

  This sub-command is the same as "`unconfig-gfarm`", but `gfservice` does some additional works. It also deletes the slave host from a server list using `gfmdhost` command and from `metadb_server_list` directive in `gfarm2.conf` file on all hosts defined in the configuration file. It also updates `gfsd.conf` file and distributes it to all gfmd and gfsd hosts, if "gfmdn_PRIVATE_MODE" variable is set to "true".

## SUB-COMMANDS FOR GFSD

The followings are sub-commands which operate `gfsd`. The given host-id argument must be "gfsdn" (gfsd1, gfsd2, ...). Otherwise `gfservice` reports an error and exits immediately.

`gfsd-status` host-id

  Exit with an exit code 0, if `gfsd` is currently running. Otherwise exits with 1.

`start-gfsd`

  Start `gfsd` if it is not running currently.

`stop-gfsd`

  Stop `gfsd` if it is running currently.

`restart-gfsd` host-id

  Perform "`stop-gfsd`" and "`start-gfsd`" sub-commands successively.

`set-gfsd-conf` host-id directive value

  Same as `set-gfsd-conf` sub-command for gfmd.

`unset-gfsd-conf` host-id directive

  Same as `unset-gfsd-conf` sub-command for gfmd.

`backup-gfsd-conf` host-id

  Same as `backup-gfsd-conf` sub-command for gfmd.

`backup-usermap` host-id

  Same as `backup-usermap` sub-command for gfmd.

`restore-gfsd-conf` host-id

  Same as `restore-gfsd-conf` sub-command for gfmd.

`restore-usermap` host-id

  Same as `restore-usermap` sub-command for gfmd.

`config-gfsd` host-id

  Execute "`config-gfsd`" command on the remote host. If "gfsdn_CONFIG_GFSD_OPTIONS" variable is declared in the configuration file of `gfservice`, its value is passed to `config-gfsd` command as options. `gfservice` also registers the configured remote host as a filesystem node using `gfhost` command. If the value of the variable "gfsdn_AUTH_TYPE" is "sharedsecret", it also copies a shared key file from gfmd1 to the gfsd host.

`unconfig-gfsd` host-id

  Execute "`stop-gfsd`" sub-command and then delete all files and directories created by gfsd.

## SUB-COMMANDS FOR CLIENT

The followings are sub-commands which operate a client. The given host-id argument must be "gfmdn" (gfmd1, gfmd2, ...), "gfsdn" (gfsd1, gfsd2, ...) or "clientn" (client1, client2, ...). Otherwise `gfservice` reports an error and exits immediately.

`mount` host-id directory option...

  Mount a Gfarm2 filesystem on directory on the remote host. The argument option is an option to `gfarm2fs` command.

`unmount` host-id directory

  Unmount a Gfarm2 filesystem on directory on the remote host.

`umount` host-id directory

  An alias of "`unmount`" sub-command.

`set-gfarm-conf` host-id directive value

  Add

      	directive value

  line to `gfarm2.conf` file on the remote host. If `gfarm2.conf` already has a directive line, `gfservice` deletes it and then add a new line.

`unset-gfarm-conf` host-id directive

  Delete a directive line in `gfarm2.conf` file on the remote host. If `gfarm2.conf` file doesn't contain directive line, the file is unchanged.

`backup-gfarm-conf` host-id

  Output `gfarm2.conf` file on the remote host to standard out.

`backup-shared-key` host-id

  Output a shared secret key file to standard out.

`restore-gfarm-conf` host-id

  Recover `gfarm2.conf` file on the remote host. `gfservice` reads a backup of `gfarm2.conf` from standard in.

`restore-shared-key` host-id

  Recover a shared secret key file on the remote host. `gfservice` reads a backup of the shared secret key from standard in.

`config-client` host-id

  Copy `gfarm2.conf` file from gfmd1 to the client host. If the value of the variable "clientn_AUTH_TYPE" is "sharedsecret", it also copies a shared key file from gfmd1 to the client host.

`unconfig-client` host-id

  Delete `gfarm2.conf` file and a shared secret key file on the remote host.

`gfcmd` host-id command-name command-argument ...

  Execute a Gfarm command on the remote host.

`gfcmd-root` host-id command-name command-argument ...

  Execute a Gfarm command on the remote host with root privilege.

`grid-proxy-init` host-id command-argument ...

  Execute `grid-proxy-init` command on the remote host.

## SUB-COMMANDS FOR MULTIPLE HOSTS

The followings are sub-commands which operate on multiple hosts. The host-id argument must not be specified.

`start-all`

  Start all backend databases, `gfmd` servers and `gfsd` servers.

`stop-all`

  Stop all `gfsd` servers, `gfmd` servers and backend databases,

`kill-gfmd-all`

  Kill (send SIGKILL) all `gfmd` servers.

`restart-all`

  Perform "`stop-all`" and "`start-all`" sub-commands successively.

`config-all`

  Perform "`config-gfarm-master`" for gfmd1 and "`config-gfarm-slave`" for all other gfmd nodes. Then, perform "`config-gfsd`" for all gfds nodes. Finally, perform "`config-client`" for all client nodes.

`unconfig-all`

  Perform "`unconfig-client`" for all client nodes. Then, perform "`unconfig-gfsd`" for all gfds nodes. Finally, perform "`unconfig-gfarm`" for all gfmd nodes.

## PLUG-IN SYSTEM

`gfservice` has a plug-in system so that user can add new sub-commands. If given sub-command is not provided by `gfservice`, `gfservice` refers to a file which has name of sub-command under %%DATADIR%%/gfarm/gfservice directory.

Sub-command file must be written as Bourne shell script. Sub-command file for sub-command "name", must have shell function named "`subcmd_name`" which will be executed from `gfservice`, and "`subcmd_name_agent`" which will be executed from `gfservice-agent`.

For the case a sub-command depends on a other user provided sub-command, Sub-command file for sub-command "name", must have shell function named "`name_depends`" which must return list of sub-commands. List of sub-commands must be a string which is space separated list of sub-command names. If sub-command or it's agent does not have dependencies, return empty string. Similarly, sub-command file must have shell function named "`name_agent_depends`" which must return list of sub-command's agents.