Skip to content

NAME

bpcp - A remote copy utility for delay tolerant networks utilizing NASA JPL's Interplanetary Overlay Network (ION)

SYNOPSIS

bpcp [OPTIONS] [source_host:]source_file_or_directory ... [destination_host:]destination_file_or_directory

DESCRIPTION

bpcp copies files and directories between hosts utilizing NASA JPL's Interplanetary Overlay Network (ION) to provide a delay tolerant network. File copies from local to remote, remote to local, or remote to remote are permitted. bpcp depends on ION to do any authentication or encryption of file transfers. All convergence layers over which bpcp runs MUST be reliable.

The command-line options are as follows:

  • -d

    Enable debug output. This option can be repeated (e.g., `-dd`) to increase the verbosity level of debug messages.

  • -q

    Quiet mode. Suppress all standard status and progress messages. Only error messages will be displayed.

  • -r

    Recursive mode. If a source path is a directory, bpcp will recursively copy its contents to the destination. If this option is not used and a source is a directory, it will be omitted with a warning message.

  • -v

    Display the bpcp version information and then exit.

  • -L bundle_lifetime

    Specify the Bundle Protocol (BP) bundle lifetime in seconds. This value determines how long a bundle will be stored in the network before being discarded if it cannot be delivered. The default value is 86400 seconds (1 day). A value of 0 results in the default lifetime.

  • -C custody_transfer_setting

    Control whether CFDP custody transfer is requested for the file transfer. Custody transfer ensures that the bundle is acknowledged by each hop in the path. Acceptable values (case-insensitive) are:

    • ON, YES, Y, 1

      To enable custody transfer.

    • OFF, NO, N, 0

      To disable custody transfer.

    The default is OFF. Custody transfer may not be provided if the underlying Bundle Protocol does not offer the service, e.g., BPv7.

  • ** -S** class_of_service

    Specify the Bundle Protocol Class of Service for this transfer. This influences the priority and handling of the bundle within the BP network. Available options are:

    • 0 (Bulk Priority)
    • 1 (Standard Priority)
    • 2 (Expedited Priority)

    The default is Standard Priority.

FILE ARGUMENTS

The file arguments specify the source(s) and destination for the copy operation. Each path can be either local or remote.

  • Local Paths

    A local path is a standard file system path on the machine where bpcp is executed (e.g., /home/user/my_file.txt or ./documents/report.pdf).

  • Remote Paths

    A remote path specifies a file or directory on another ION node. It is formatted as host:remote_path. The host is the numeric ION node number (e.g., 1 for a node with Endpoint ID 'ipn:1.0'). The remote_path is the absolute or relative file system path on the remote host (e.g., 1:/remote/data/file.bin or 1:./data/file.bin).

    If no path is specified after the colon (e.g., 1: ), the remote host's current working directory (.) is assumed as the source or destination.

Copying Behavior

  • Single Source Copy

    When two arguments are provided (e.g., bpcp source destination):

    • If destination is an existing directory, source will be copied into that directory, retaining its original filename.
    • If destination does not exist or is a file, source will be copied to destination with the specified name.

  • Multiple Source Copy

    When more than two arguments are provided (e.g., bpcp source1 source2 ... destination):

    • The last argument is always interpreted as the destination directory.
    • All preceding source arguments (files or directories) will be copied into this destination directory.
    • If the destination directory does not exist locally, bpcp will report an error. If it is a remote destination, bpcp will attempt to create it if CFDP supports it, but typically it expects the remote directory to exist or will copy files into the specified remote path as if it were a file name.

Important Considerations

bpcp utilizes CFDP (CCSDS File Delivery Protocol) for actual file transfers. This implies:

    1. ION's CFDP implementation requires the use of reliable convergence layers.
    1. File permissions are NOT transferred. Copied files will typically be made executable on the destination system.
    1. Symbolic links are handled differently: for local-to-remote transfers, symbolic links are ignored; for remote-to-local or remote-to-remote transfers, the target of the symbolic link is copied, not the link itself.
    1. All hosts must be specified using ION's IPN naming scheme (e.g., `ipn:node_number.service_number`).
    1. To perform remote-to-local or remote-to-remote transfers, the bpcpd daemon MUST be running on the remote hosts involved in the transfer.
    1. bpcp should NOT be run simultaneously with bpcpd or cfdptest on the same system, as they may interfere with each other's CFDP operations.

EXIT STATUS

  • 0

    bpcp terminated normally, indicating successful completion of the copy operations.

  • 1

    bpcp terminated abnormally, indicating an error occurred. Refer to the console output and the ion.log file for specific error messages and details.

FILES

No configuration files are needed for bpcp.

ENVIRONMENT

No environment variables directly apply to bpcp's operation.

BUGS

Report bugs to https://github.com/nasa-jpl/ION-DTN/issues

SEE ALSO

bpcpd(1), cfdptest(1), ion(3)