GFSERVICE(1)

📦 version 2.7.20, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

GFSERVICE(1) 💅

okay bestie, welcome to the Gfarm corner of the manual universe — this is gfservice, and she is that girl. ✨

✨ NAME ✨

gfservice — control Gfarm servers from a remote host 🫶

✨ SYNOPSIS ✨

gfservice [options] sub-command [host-id] [argument ...]

✨ DESCRIPTION ✨

so basically, gfservice is the little utility Gfarm admins use to boss around servers (gfmd, gfsd and PostgreSQL) on remote hosts. OpenLDAP is not supported currently — like, she's just not doing that rn, okay? 🙈

what she can do: start, stop, set up (she runs config-gfarm and config-gfsd for you) and clean up the servers. lowkey iconic, highkey useful. 💖

a sample command line looks like this:

gfservice start-gfmd gfmd2

where start-gfmd is a sub-command and gfmd2 is a host-id respectively. so when you run that, gfservice tries to start gfmd on the host named gfmd2. to point at a remote server host, gfservice uses a host-id instead of a hostname — yes bestie, they're different things, keep up 💅.

all the host-ids (gfmd1, gfmd2, and so on) live in a configuration file of gfservice. here's a lil example of that 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

now, how does gfservice decide which config file to read? she follows these procedures, in order:

if the -f file option is specified, she reads that file. periodt.
otherwise, if the environment variable GFSERVICE_CONF is defined and not empty, she reads that file.
otherwise, she reads $HOME/.gfservice.

if gfservice fails to read a configuration file, she prints an error message and exits immediately — no vibes, no waiting. 😭

⚠️ heads up: the configuration file itself is a Bourne-shell script, and gfservice includes (exactly to say, evaluates) the file. so like… she's running it, bestie. see gfservice.conf(5) for more details about the configuration file.

gfservice uses SSH (Secure Shell) to connect with a remote host. and since she 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, so you're not typing your passphrase every single time. imagine. 💀

in addition to SSH, gfservice uses Sudo to get root privilege on the remote host. please add a line like the one below to the 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 for a password several times if you omit it. (and by "may" we mean "will", and by "several" we mean "you will be typing forever". 😭)

since gfservice executes an agent command named gfservice-agent on the remote host using SSH and Sudo, the gfservice-agent command must have been installed on all hosts you want to operate using gfservice. no agent, no service, that's the rule. 🌸

oh and — gfservice has a plug-in system so that user can add new sub-commands. see the "PLUG-IN SYSTEM" section of this man page for more details. yes she's extensible, she contains multitudes. 💖

✨ OPTIONS ✨

-d — print debug information. gfservice passes this option to gfservice-agent so that also gfservice-agent outputs debug information. double the debug, double the fun. 🔥
-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), she waits until the operation is complete or the time interval is elapsed. if "no" is specified as time, timeout never occurs. the default value is "no". (so by default she's patient. very demure. very mindful. 🎀)
-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. and listen — the given host-id argument must be "gfmdn" (gfmd1, gfmd2, ...). otherwise gfservice reports an error and exits immediately. she is not flexible about this. she is not going to figure it out for you. 😤

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. yeah, she said what she said. 💀
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. glow up moment fr fr 👑
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. out with the old, in with the new ✨

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 master gfmd to the slave gfmd host. she does a lot, okay? she's carrying this whole operation. 💅
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".

…and bestie, that's literally not even all of it, don't go anywhere 💖

✨ SUB-COMMANDS FOR GFSD ✨

Okay bestie, these ones drive gfsd around 💅. And listen — the host-id you hand over must be gfsdn shaped (gfsd1, gfsd2, …). If it's not, gfservice just goes "nope" and exits immediately, no negotiation, no vibe check. 😭

gfsd-status host-id — exits with code 0 if gfsd is running right this second. If it's not? Exits with 1. That's it, that's the whole personality. ✨
start-gfsd — starts gfsd, but only if it isn't already running. No double-starting, we're not messy. 🎀
stop-gfsd — stops gfsd, but only if it is currently running. Considerate. 🫶
restart-gfsd host-id — does stop-gfsd and then start-gfsd, one right after the other. Glow-up arc, basically. 🌸
set-gfsd-conf host-id directive value — same as the set-gfsd-conf sub-command for gfmd. 👑
unset-gfsd-conf host-id directive — same as the unset-gfsd-conf sub-command for gfmd.
backup-gfsd-conf host-id — same as the backup-gfsd-conf sub-command for gfmd.
backup-usermap host-id — same as the backup-usermap sub-command for gfmd.
restore-gfsd-conf host-id — same as the restore-gfsd-conf sub-command for gfmd.
restore-usermap host-id — same as the restore-usermap sub-command for gfmd.
config-gfsd host-id — runs the config-gfsd command on the remote host. If the variable gfsdn_CONFIG_GFSD_OPTIONS is declared in the config file of gfservice, its value gets passed to the config-gfsd command as options. gfservice also registers that configured remote host as a filesystem node using the gfhost command. And if the value of the variable gfsdn_AUTH_TYPE is sharedsecret, it also copies a shared key file from gfmd1 over to the gfsd host. 🔥
unconfig-gfsd host-id — runs the stop-gfsd sub-command and then deletes all files and directories that gfsd created. Full clear-out. 💀

💜 SUB-COMMANDS FOR CLIENT 💜

Now we're doing client stuff. The host-id here has to be gfmdn (gfmd1, gfmd2, …), gfsdn (gfsd1, gfsd2, …) or clientn (client1, client2, …). Get it wrong and gfservice reports an error and exits immediately. Be so serious. 😤

mount host-id directory option... — mounts a Gfarm2 filesystem on directory on the remote host. Each option is an option to the gfarm2fs command. 🌈
unmount host-id directory — unmounts a Gfarm2 filesystem on directory on the remote host.
umount host-id directory — an alias of the unmount sub-command. Same girl, different name. 💅
set-gfarm-conf host-id directive value — adds a line

directive value

to the gfarm2.conf file on the remote host. If gfarm2.conf already has a directive line, gfservice deletes it and then adds a new line. Out with the old, in with the new. ✨

unset-gfarm-conf host-id directive — deletes a directive line in the gfarm2.conf file on the remote host. If the gfarm2.conf file doesn't contain that directive line, the file stays unchanged. No touchy. 🙈
backup-gfarm-conf host-id — outputs the gfarm2.conf file on the remote host to standard out. 📤
backup-shared-key host-id — outputs a shared secret key file to standard out. 🔐
restore-gfarm-conf host-id — recovers the gfarm2.conf file on the remote host. gfservice reads a backup of gfarm2.conf from standard in. 📥
restore-shared-key host-id — recovers 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 — copies the 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 — deletes the gfarm2.conf file and a shared secret key file on the remote host.
gfcmd host-id command-name command-argument ... — executes a Gfarm command on the remote host. 🎀
gfcmd-root host-id command-name command-argument ... — executes a Gfarm command on the remote host with root privilege. Main character energy, but make it root. 👑
grid-proxy-init host-id command-argument ... — executes the grid-proxy-init command on the remote host. ⭐

🌟 SUB-COMMANDS FOR MULTIPLE HOSTS 🌟

These ones operate on a whole squad of hosts at once. And here's the thing — the host-id argument must not be specified. Don't even try it bestie. 🚫

start-all — starts all backend databases, gfmd servers and gfsd servers. Everybody up! 🎉
stop-all — stops all gfsd servers, gfmd servers and backend databases,
kill-gfmd-all — kills (sends SIGKILL) all gfmd servers. Dramatic? Yes. Necessary? Also yes. 💀
restart-all — performs the stop-all and start-all sub-commands successively.
config-all — performs config-gfarm-master for gfmd1 and config-gfarm-slave for all other gfmd nodes. Then, performs config-gfsd for all gfds nodes. Finally, performs config-client for all client nodes. It's giving assembly line. 🏭
unconfig-all — performs unconfig-client for all client nodes. Then, performs unconfig-gfsd for all gfds nodes. Finally, performs unconfig-gfarm for all gfmd nodes. Reverse order, we're dismantling the whole thing. 🧹

🧚 PLUG-IN SYSTEM 🧚

Not me telling you gfservice is literally extensible?? It has a plug-in system so you — yes YOU — can add new sub-commands. If a given sub-command isn't provided by gfservice, it goes looking for a file with the name of that sub-command under the %%DATADIR%%/gfarm/gfservice directory. iykyk. 🌸

The sub-command file must be written as a Bourne shell script. For a sub-command called name, the sub-command file must have a 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 where a sub-command depends on another user-provided sub-command, the sub-command file for sub-command name must have a shell function named name_depends, which must return a list of sub-commands. That list of sub-commands must be a string which is a space separated list of sub-command names. If the sub-command or its agent does not have dependencies, return an empty string. Similarly, the sub-command file must have a shell function named name_agent_depends, which must return a list of the sub-command's agents. 🫶

Bestie reminder: those function names and that path are exact. Shell function names don't do nicknames. 💅

And that's the whole page, gorgeous. 🌈 This one's from the Gfarm crew, dated 6 Jun 2013, filed under GFSERVICE(1) — go forth and configure your cluster, you absolute icon. 💖✨🎀

📦 where this page comes from

debian bookworm: gfarm-client 2.7.20+dfsg-1+b2 · BSD-like
debian trixie: gfarm-client 2.7.20+dfsg-1.2+b1 · BSD-like
ubuntu noble: gfarm-client 2.7.20+dfsg-1.1ubuntu1 · BSD-like
ubuntu questing: gfarm-client 2.7.20+dfsg-1.2
ubuntu resolute: gfarm-client 2.7.20+dfsg-1.3 · BSD-like
ubuntu stonking: gfarm-client 2.7.20+dfsg-1.3build1 · BSD-like
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms