Provided by: gfarm-client_2.7.20+dfsg-1build1_amd64 bug

NAME

       gfservice - control Gfarm servers from a remote host

SYNOPSIS

       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.