gfservice - control Gfarm servers from a remote host
gfservice [options] sub-command [host-id]
[argument ...]
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.
-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
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
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
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.
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.