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:
-f
file
option is specified, read
file
.
Otherwise, the environment variable
GFSERVICE_CONF
is defined and not empty, read the file.
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.
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.
host-id
Exit with an exit code 0, if a backend database is currently running. Otherwise exits with 1.
host-id
Exit with an exit code 0, if gfmd is currently running. Otherwise exits with 1.
host-id
Start a backend database if it is not running currently.
host-id
Start gfmd if it is not running currently.
host-id
An alias of "start-gfmd" sub-command.
host-id
This sub-command is the same as "start-gfmd",
but -S
option is added to gfmd.
host-id
Start a backend database and gfmd if they are not running currently.
host-id
An alias of "start-gfarm" sub-command.
host-id
This sub-command is the same as "start-gfarm",
but -S
option is added to gfmd.
host-id
Stop a backend database if it is running currently.
host-id
Stop gfmd if it is running currently.
host-id
Stop gfmd and a backend database if they are running currently.
host-id
Kill gfmd (send SIGKILL) if it is running currently.
host-id
Perform "stop-backend-db" and "start-backend-db" sub-commands successively.
host-id
Perform "stop-gfmd" and "start-gfmd" sub-commands successively.
host-id
An alias of "restart-gfmd" sub-command.
host-id
Perform "stop-gfmd" and "start-gfmd-slave" sub-commands successively.
host-id
Perform "stop-gfarm" and "start-gfarm" sub-commands successively.
host-id
An alias of "restart-gfarm" sub-command.
host-id
Perform "stop-gfarm" and "start-gfarm-slave" sub-commands successively.
host-id
Promote gfmd from a slave to a master.
host-id
An alias of "promote" sub-command.
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.
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.
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.
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 a backend database on the remote host and output the backup data to standard out.
host-id
Output gfmd.conf
file on the remote host to
standard out.
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.
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.
host-id
Restore a backend database on the remote host. The backup data are read from standard in.
host-id
Recover gfmd.conf
file on the remote host.
gfservice reads a backup of gfmd.conf
from standard in.
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.
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.
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.
host-id
This sub-command is the same as config-gfarm but gfmd replication is enabled automatically.
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.
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.
host-id
An alias of "unconfig-gfarm" sub-command.
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".
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.
host-id
Exit with an exit code 0, if gfsd is currently running. Otherwise exits with 1.
Start gfsd if it is not running currently.
Stop gfsd if it is running currently.
host-id
Perform "stop-gfsd" and "start-gfsd" sub-commands successively.
host-id
directive
value
Same as set-gfsd-conf sub-command for gfmd.
host-id
directive
Same as unset-gfsd-conf sub-command for gfmd.
host-id
Same as backup-gfsd-conf sub-command for gfmd.
host-id
Same as backup-usermap sub-command for gfmd.
host-id
Same as restore-gfsd-conf sub-command for gfmd.
host-id
Same as restore-usermap sub-command for gfmd.
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.
host-id
Execute "stop-gfsd" sub-command and then delete all files and directories created by gfsd.
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.
host-id
directory
option...
Mount a Gfarm2 filesystem on directory
on the
remote host.
The argument option
is an option to
gfarm2fs command.
host-id
directory
Unmount a Gfarm2 filesystem on directory
on the
remote host.
host-id
directory
An alias of "unmount" sub-command.
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.
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.
host-id
Output gfarm2.conf
file on the remote host to
standard out.
host-id
Output a shared secret key file to standard out.
host-id
Recover gfarm2.conf
file on the remote host.
gfservice reads a backup of gfarm2.conf
from standard in.
host-id
Recover a shared secret key file on the remote host. gfservice reads a backup of the shared secret key from standard in.
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.
host-id
Delete gfarm2.conf
file and a shared secret key file
on the remote host.
host-id
command-name
command-argument ...
Execute a Gfarm command on the remote host.
host-id
command-name
command-argument ...
Execute a Gfarm command on the remote host with root privilege.
host-id
command-argument ...
Execute grid-proxy-init command on the remote host.
The followings are sub-commands which operate on multiple hosts. The host-id argument must not be specified.
Start all backend databases, gfmd servers and gfsd servers.
Stop all gfsd servers, gfmd servers and backend databases,
Kill (send SIGKILL) all gfmd servers.
Perform "stop-all" and "start-all" sub-commands successively.
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.
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_
" which
will be executed from gfservice, and
"name
subcmd_
"
which will be executed from gfservice-agent.
name
_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
"
" 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
_depends
"
which must return list of sub-command's agents.
name
_agent_depends