GFPCOPY(1)

💖 GFPCOPY(1) — the Gfarm parallel-copy bestie 💖

okay so real talk: this is the manual page for gfpcopy, one of the Gfarm girlies, and she is that girl. Gfarm energy, parallel everything, directory recursion, the works. Let's get into it 💅

---

✨ NAME ✨

gfpcopy — copy Gfarm files in parallel 🦋

---

✨ SYNOPSIS ✨

gfpcopy [-nqvdpPU] [-X regexp] [-S source-domainname]
        [-h source-hostfile] [-D destination-domainname]
        [-H destination-hostfile] [-j num-of-processes]
        [-J num-of-processes] [-M limit-byte] [-z minimum-byte]
        [-Z maximum-byte] [-w way-of-scheduling]
        [-W kilobytes-for-threshold] [-s KB/s-to-simulate]
        [-F num-for-readahead] [-b bufsize] [-f] [-e] [-k] source-path
        destination-path

---

✨ DESCRIPTION ✨

So basically, gfpcopy copies files in parallel. Like, multiple at once. Iconic behaviour fr fr 🔥

When the source-path is a directory, the files under that directory get copied recursively. It goes all the way down, no cap.

When the destination-path does not exist, the directory is created. When the destination-path does exist, a directory with the same name as the source-path gets created underneath the destination-path. The way she just handles that for you 😌

A set of source/destination hosts can be specified by a domain name and/or a hostlist file. When both a domain name and a hostlist file are specified, the set of hosts is determined by both conditions together (yes, both, they collab). When a set of source hosts is specified, only files stored on those source hosts get copied.

gfpcopy also retrieves the directory entries in parallel too, because why would she do anything one at a time 🌈

---

✨ SOURCE PATH ✨

source-path has to be one of these formats, bestie. Also heads up: files on HPSS cannot be copied. 💀

• path-name — this is a relative path or an absolute path of a local file system. When the path is a mount point on gfarm2fs, files are copied without passing through the gfarm2fs. Sneaky (affectionate).
• gfarm:... — this is a Gfarm URL 🎀
• file:... — this is an URL of a local file system.

---

✨ DESTINATION PATH ✨

destination-path has to be one of these formats:

• path-name — a relative path or an absolute path of a local file system. When the path is a mount point on gfarm2fs, files are copied without passing through the gfarm2fs.
• gfarm:... — a Gfarm URL of a directory.
• file:... — an URL of a directory on a local file system.
• hpss:... — an URL of a directory on HPSS. ⚠️ If the same directory as the source-path exists under this directory, the source-path cannot be copied. Also the differential copy is not supported for HPSS, so don't come for her about that. Relative paths like hpss:. and hpss:dir can be specified though 🫶

---

✨ GFPCOPY OPTIONS ✨

These are the options that are only for gfpcopy, her exclusive little set 💅

• -b bufsize — Specifies the buffer size in bytes to copy. The default value is 64 KiB (64 * 1024).
• -f — With the -f option, existing files will be overwritten when the size is different or the modification time (mtime) is different from the source file. Without the -f option, existing files will be overwritten when they are older than the corresponding source files in the modification time. Pick your fighter ✨
• -e — Skips existing files in order to execute gfpcopy simultaneously. She's not redoing work, periodt.
• -k — Does not copy symbolic links. 🚫🔗

---

✨ COMMON OPTIONS ✨

The following options are common options for gfprep and gfpcopy — shared besties 🫶

• -X regexp — Skips files matched by the pattern of regexp. When multiple patterns need to be specified, specify -X options multiple times. Stack 'em up 🧚
• -S source-domainname — Creates file replicas or copies files only stored on the hosts in the specified domain name.
• -h source-hostfile — Creates file replicas or copies files only stored on the hosts listed in the specified hostfile. The source-hostfile consists of a file system node name on each line. If - is specified, standard input is used to read the host list. 👀
• -L — Creates file replicas or copies files from the hosts specified by the -S or -h option.
• -D destination-domainname — Specifies the domain name for destination. If neither this nor the -H option is specified, replicas may be copied to any available host. Free spirit 💫
• -H destination-hostfile — Specifies a file which describes hostnames for destination. The destination-hostfile consists of a file system node name on each line. If - is specified, standard input is used to read the host list.
• -j num-of-processes — Specifies the maximum number of processes to create file replicas (or copy files) simultaneously. The default value is the parameter of client_parallel_copy in gfarm2.conf. (see man gfarm2.conf) The maximum number of process per file system node for source or destination is the number of CPUs (see man gfhost). 🖥️✨
• -J num-of-processes — Specifies the number of processes to retrieve directory entries in parallel. The default value is 8.
• -M total-byte — Specifies the total file size in bytes to replicate or copy. This option is useful to increase the available capacity by moving the specified bytes of files. The default value is unlimited. ♾️
• -z minimum-byte — Specifies the minimum file size in bytes to replicate or copy. This option is useful not to replicate or copy small files. The default value is unlimited.
• -Z maximum-byte — Specifies the maximum file size in bytes to replicate or copy. This option is useful not to replicate or copy large files. The default value is unlimited.
• -w way-of-scheduling — Specifies a scheduling method. noplan replicates/copies while finding files. greedy schedules greedily the order of replication/copy beforehand. The default behavior is noplan. ⚠️ greedy scheduling cannot be used with the -N option and -m option.
• -W kibibytes — Specifies a threshold size/cost (KiB) to flat costs of Connections. A Connection means a scheduling information to assign files per a child-process. This option is effective with -w greedy. The default value is 50*1024 KiB (50 MiB).
• -I sec-to-update — Specifies the interval in seconds to collect load average and available capacity. Default is 300 seconds. ⏰
• -B — Gfarm 2.6.16 or later does not select high loaded file system nodes. This option disables this feature. High loaded node is defined by having more CPU load than schedule_busy_load_thresh * number of CPUs. For details of schedule_busy_load_thresh, refer to a manual page of gfarm2.conf. She's tired, let her rest 😭
• -U — Disables checking the available disk space of the selected node every time.
• -F num-of-dirents — Specifies the number of readahead entries to retrieve the directory entries. The default value is 10000.
• -s kilobytes-per-second — Specifies a throughput (KB/s) to simulate the replication/copy, and does nothing (gets file information only). Fake it till you make it 💅
• -n — Does nothing.
• -p — Reports the total performance information. 📊
• -P — Reports the performance information for each file and all files.
• -q — Suppresses non-error messages. 🤫
• -v — Displays verbose output.
• -d — Displays debug output. 🐛
• -? — Displays a list of command options.

---

✨ EXAMPLES ✨

To copy files under the directory recursively:

$ gfpcopy gfarm:///dir file:///tmp/dir

$ gfpcopy file:///tmp/dir gfarm:///dir

$ gfpcopy gfarm:///dir1 gfarm:///dir2

$ gfpcopy gfarm:///dir hpss:///tmp/dir

$ cd /mnt/gfarm2fs
$ gfpcopy dir /tmp/dir

To copy a file:

$ gfpcopy gfarm:///dir/file file:///dir

$ cd /mnt/gfarm2fs
$ gfpcopy file /tmp/dir

---

✨ NOTES ✨

To retrieve the directory entries efficiently, it is better to execute the gfpcopy command near the metadata server. When you need to execute the gfpcopy command far from the metadata server, increase the parallelism by the -j and -J options. Basically: stay close to the metadata server, or turn the parallel dials way up 🌸

---

✨ SEE ALSO ✨

gfprep(1), gfreg(1), gfexport(1), gfarm2.conf(5)

---

💖 that's the whole page bestie, you ate it. go copy some files in parallel, you've got this 🫶

this has been the Gfarm manual page for gfpcopy, from the Gfarm girlies — dated 27 Aug 2015 ✨