From 19c73af09d6262d41039c0906f5ea88471075910 Mon Sep 17 00:00:00 2001 From: Ryo Nakamura Date: Sun, 18 Feb 2024 21:34:41 +0900 Subject: update console output and doc --- doc/mscp.1.in | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- doc/mscp.rst | 42 +++++++++++++++++++++++++++++++++++- src/checkpoint.c | 10 ++++----- src/main.c | 1 + 4 files changed, 111 insertions(+), 8 deletions(-) diff --git a/doc/mscp.1.in b/doc/mscp.1.in index 2bccfe8..a56e26c 100644 --- a/doc/mscp.1.in +++ b/doc/mscp.1.in @@ -20,6 +20,12 @@ mscp \- copy files over multiple SSH connections .BI \-I \ INTERVAL\c ] [\c +.BI \-W \ CHECKPOINT\c +] +[\c +.BI \-R \ CHECKPOINT\c +] +[\c .BI \-s \ MIN_CHUNK_SIZE\c ] [\c @@ -131,6 +137,47 @@ single source IP address for a short period as a brute force attack. This option inserts intervals between the attempts to avoid being determined as an attack. The default value is 0. +.TP +.B \-W \fICHECKPOINT\fR +Specifies a checkpoint file path to save the state of a failed +transfer. When transferring fails due to, for example, connection +disruption or user interrupt, +.B mscp +writes the information about remaining files and chunks to the +specified checkpoint file. +.B \-W +option with +.B \-D +(dry-run mode) only writes a checkpoint file and exits. + + +.TP +.B \-R \fICHECKPOINT\fR +Specifies a checkpoint file path to resume a transfer. When this +option with a checkpoint file is passed, +.B mscp +loads a remote host, copy direction, and files and their chunks to be +transferred from the checkpoint file. Namely, +.B mscp +can resume a past failed transfer from the checkpoint. Resumeing with +a checkpoint does not require +.I source ... target +arguments. Other options for establishing SSH connections, for +example, username, port number, config file, should be specified as +with the failed run. In addition, checkpoint files contain files as +relative paths. Thus, you must run +.B mscp +in the same working directory as the failed run. + + +You can see contents of a checkpoint file with +.B mscp +.I \-vvv \-D \-R CHECKOPOINT +command. + + + + .TP .B \-s \fIMIN_CHUNK_SIZE\fR Specifies the minimum chunk size. @@ -306,6 +353,24 @@ Copy a local file and a directory to /tmp at a remote host: $ mscp ~/src-file dir1 10.0.0.1:/tmp .fi +.PP +Save a checkpoint if transfer fails: + +.nf + $ mscp -W checkpoint srcdir 10.0.0.1:dst/ +.fi + +.PP +Check remaining files and chunkes, and resume a failed transfer: + +.nf + # dump a checkpoint and exit (dry-run mode) + $ mscp -vvv -D -R checkpoint + + # resume transferring from the checkpoint + $ mscp -R checkpoint +.fi + .PP In a long fat network, following options might improve performance: @@ -324,7 +389,6 @@ will be faster than the default chacha20-poly1305 cipher, particularly on hosts that support AES-NI. - .SH "SEE ALSO" .BR scp (1), .BR ssh (1), diff --git a/doc/mscp.rst b/doc/mscp.rst index 48a8455..a183dde 100644 --- a/doc/mscp.rst +++ b/doc/mscp.rst @@ -2,7 +2,7 @@ MSCP ==== -:Date: v0.1.4 +:Date: v0.1.4-19-g5f628b6 NAME ==== @@ -14,6 +14,7 @@ SYNOPSIS **mscp** [**-46vqDpHdNh**] [ **-n**\ *NR_CONNECTIONS* ] [ **-m**\ *COREMASK* ] [ **-u**\ *MAX_STARTUPS* ] [ **-I**\ *INTERVAL* ] [ +**-W**\ *CHECKPOINT* ] [ **-R**\ *CHECKPOINT* ] [ **-s**\ *MIN_CHUNK_SIZE* ] [ **-S**\ *MAX_CHUNK_SIZE* ] [ **-a**\ *NR_AHEAD* ] [ **-b**\ *BUF_SIZE* ] [ **-l**\ *LOGIN_NAME* ] [ **-P**\ *PORT* ] [ **-F**\ *CONFIG* ] [ **-i**\ *IDENTITY* ] [ @@ -69,6 +70,29 @@ OPTIONS option inserts intervals between the attempts to avoid being determined as an attack. The default value is 0. +**-W CHECKPOINT** + Specifies a checkpoint file path to save the state of a failed + transfer. When transferring fails due to, for example, connection + disruption or user interrupt, **mscp** writes the information about + remaining files and chunks to the specified checkpoint file. **-W** + option with **-D** (dry-run mode) only writes a checkpoint file and + exits. + +**-R CHECKPOINT** + Specifies a checkpoint file path to resume a transfer. When this + option with a checkpoint file is passed, **mscp** loads a remote + host, copy direction, and files and their chunks to be transferred + from the checkpoint file. Namely, **mscp** can resume a past failed + transfer from the checkpoint. Resumeing with a checkpoint does not + require *source ... target* arguments. Other options for establishing + SSH connections, for example, username, port number, config file, + should be specified as with the failed run. In addition, checkpoint + files contain files as relative paths. Thus, you must run **mscp** in + the same working directory as the failed run. + +You can see contents of a checkpoint file with **mscp** *-vvv -D -R +CHECKOPOINT* command. + **-s MIN_CHUNK_SIZE** Specifies the minimum chunk size. **mscp** divides a file into chunks and copies the chunks in parallel. @@ -199,6 +223,22 @@ Copy a local file and a directory to /tmp at a remote host: $ mscp ~/src-file dir1 10.0.0.1:/tmp +Save a checkpoint if transfer fails: + +:: + + $ mscp -W checkpoint srcdir 10.0.0.1:dst/ + +Check remaining files and chunkes, and resume a failed transfer: + +:: + + # dump a checkpoint and exit (dry-run mode) + $ mscp -vvv -D -R checkpoint + + # resume transferring from the checkpoint + $ mscp -R checkpoint + In a long fat network, following options might improve performance: :: diff --git a/src/checkpoint.c b/src/checkpoint.c index 1e5ce29..efa1926 100644 --- a/src/checkpoint.c +++ b/src/checkpoint.c @@ -133,8 +133,6 @@ int checkpoint_save(const char *pathname, int dir, char *remote, pool *path_pool return -1; } - pr_notice("checkppoint: save to %s", pathname); - /* write meta */ memset(&meta, 0, sizeof(meta)); meta.hdr.type = OBJ_TYPE_META; @@ -173,7 +171,7 @@ int checkpoint_save(const char *pathname, int dir, char *remote, pool *path_pool nr_chunks++; } - pr_info("checkpoint: %u paths and %u chunks saved", nr_paths, nr_chunks); + pr_notice("checkpoint: %u paths and %u chunks saved", nr_paths, nr_chunks); return 0; } @@ -201,7 +199,7 @@ static int checkpoint_load_meta(struct checkpoint_obj_hdr *hdr, char *remote, si snprintf(remote, len, "%s", meta->remote); *dir = meta->direction; - pr_notice("checkpoint: loaded, remote=%s direction=%s", meta->remote, + pr_notice("checkpoint: remote=%s direction=%s", meta->remote, meta->direction == MSCP_DIRECTION_L2R ? "local-to-remote" : meta->direction == MSCP_DIRECTION_R2L ? "remote-to-local" : "invalid"); @@ -237,7 +235,7 @@ static int checkpoint_load_path(struct checkpoint_obj_hdr *hdr, pool *path_pool) return -1; } - pr_info("checkpoint: %s -> %s", p->path, p->dst_path); + pr_info("checkpoint:path: %s -> %s", p->path, p->dst_path); return 0; } @@ -263,7 +261,7 @@ static int checkpoint_load_chunk(struct checkpoint_obj_hdr *hdr, pool *path_pool return -1; } - pr_debug("checkpoint: %s 0x%lx-0x%lx", p->path, c->off, c->off + c->len); + pr_debug("checkpoint:chunk: %s 0x%lx-0x%lx", p->path, c->off, c->off + c->len); return 0; } diff --git a/src/main.c b/src/main.c index b6e8266..be4307e 100644 --- a/src/main.c +++ b/src/main.c @@ -483,6 +483,7 @@ out: ret = 1; if ((dryrun || ret != 0) && checkpoint_save) { + print_cli("save checkpoint to %s\n", checkpoint_save); if (mscp_checkpoint_save(m, checkpoint_save) < 0) { pr_err("mscp_checkpoint_save: %s", priv_get_err()); return -1; -- cgit v1.2.3