8.1.1. NGCLIENT

8.1.1.1. SYNOPSIS

ngclient authenticate (-u USERNAME [-p PASSWORD] | -T TOKEN) [-k NAME]

ngclient migrate path... [-s site] [-r] [-p] [options...]

ngclient recall path... [-s site] [-r] [options...]

ngclient send path... [-s source] -t target [options...]

ngclient workflows COMMAND

ngclient features COMMAND

8.1.1.2. DESCRIPTION

ngclient is a CLI wrapper for the default Ngenea Hub workflows - migrate, recall, and send. It also provides a mechanism for generating authentication tokens.

ngclient settings can be read from a config file, rather than being passed on the command line. See ngenea-client.conf(5) for more information on the configuration format. CLI flags take precedence over config file settings.

The authenticate command can be used to generate a client key from a username or access token. The generated client key will be printed to stdout. That client key can then be used with the workflow sub-commands, either via the --client-key flag, or by saving it to the ngenea-client.conf(5) configuration file.

The workflows command group contains sub-commands for interacting with workflows, such as listing workflows and importing new one. See ngclient-workflows(1) for more details.

The features command group contains sub-commands for listing, enabling, or disabling feature flags. See ngclient-features(1) for more details.

8.1.1.3. OPTION SUMMARY

      path...              One paths to call the workflow on

-T, --access-token TOKEN   Access token to authenticate with
-u, --username USERNAME    Username to authenticate with
-p, --password PASSWORD    Password for the authentication username
-k, --key-name NAME        Unique name for the client key

    --base-url             Base URL of the {{ brand_name }} API

-c, --config CONFIG        Alternative configuration file path
    --client-key KEY       Client API key to authenticate with

-s, --site SITE            Site to perform the workflow on
-t, --target TARGET        Site to send files to

-d, --no-wait              Exit after job is submitted, don't wait for it to complete
    --timeout SECONDS      wait for completion timeout. If not set, wait indefinitely

-r, --recursive            Perform task recursively.
-p, --premigrate           Premigrate files from site
-H, --hydrate              Hydrate files on the send target site

-h, --help                 Print help message and exit

8.1.1.3.1. OPTIONS

  • -T, --access-token

    An access token to generate a client key with.

  • -u, --username

    Username to generate a client key with.

  • -p, --password

    Password to use in combination with --username

    If --username is specified and --password isn't, you will be prompted to enter a password interactively. This may be preferrable so that the password doesn't appear in shell history.

  • -k, --key-name

    A unique name to assign when generating a client key.

    This will be displayed in the Ngenea Hub UI

    If not specified, a random uuid will be generated for the key name.

  • --base-url

    Base URL of the Ngenea Hub API, which operations will be performed against.

    This can be used to perform Ngenea Hub operations on a remote server.

    If not specified, the default is http://localhost:8000/api

  • -c, --config

    The path to an alternative configuration file.

    If not specified, the default configuration paths will be used. The default paths are in the user's HOME directory $HOME/.config/ngenea/ngenea-client.conf, and the global configuration at /etc/ngenea/ngenea-client.conf

    See ngenea-client.conf(5) for more information on the configuration format.

    Command line options take precedence over any corresponding config file settings.

  • -D, --no-verify

    Disables TLS Verification

    By default, ngclient will verify TLS certificate at the remote end.

    With this flag, requests made by ngclient will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates.

  • --client-key

    Ngenea Hub authentication client key.

    This can be generated via the Ngenea Hub REST API, or using ngclient(1) authenticate

  • -s, --site

    Site to use for workflows.

    For migrate and recall, this is the site where the workflows execute. For send, this is the source site, from which files are sent.

    Site does not have to match the node where ngclient is being called. This can be used to migrate/recall/send files from a remote site.

    Note - shell-globbing will be evaluated on the local node. For a remote site, the files that the glob would match may differ.

  • -t, --target

    Target site for the send workflow

  • -d, --no-wait

    Don't wait for workflows to complete.

    By default, ngclient will wait for the workflow to complete, subject to --timeout.

    With this flag, ngclient will exit immediately. The workflow will continue to execute independently. In that case, the workflow can be monitored in the Ngenea Hub UI

  • --timeout

    How long to wait for workflows to complete, in seconds.

    If not specified, ngclient will wait indefinitely.

    If the workflow doesn't complete within the timeout, the client will exit with an error. The workflow itself may continue to execute.

  • -r, --recursive

    Migrate or recall files and directories recursively.

  • -p, --premigrate

    Premigrate files

    Premigrated files are migrated, but the data is kept resident.

  • -H, --hydrate

    Controls whether the send workflow 'hydrates' files on the target.

    If false, files are only reverse stubbed on the target.

  • -h, --help

    Prints the help message.

8.1.1.4. EXAMPLES

8.1.1.4.1. GENERATE A CLIENT KEY

$ ngclient authenticate --username pixadmin -k ngclient-pixadmin
pixadmin's password:

jDBh2cRk6.LswQfylT2BtGiqtYUWhMB1iipJmQNgr

NOTE: The authenticate command doesn't read config values from the config file, so the --no-verify and --base-url arguments should be passed as cmd arguments if default values aren't required

8.1.1.4.2. RECALL A FILE

ngclient recall /mmfs1/data/hello.txt -s site1 --client-key jDBh2cRk6.LswQfylT2BtGiqtYUWhMB1iipJmQNgr

For brevity, the site and client-key can be saved to the config file

8.1.1.4.3. PREMIGRATE A DIRECTORY RECURSIVELY

Assuming the site and client key has been saved to the config file

ngclient migrate /mmfs1/data/sample_data/cats -p -r

8.1.1.4.4. SEND A FILE TO A REMOTE SITE

ngclient send /mmfs1/data/hello.txt -s site1 -t site2 --hydrate

8.1.1.5. AVAILABILITY

Distributed as part of the ngenea-hub-client rpm, or the ngclient wheel (Python) for non-Red Hat based systems.

The ngclient wheel can be installed and run on any operating system.

Note - transparent_recall(1) is packaged along with ngclient, but transparent_recall will only work on Unix-based operating systems.

8.1.1.6. SEE ALSO

ngenea-client.conf(5), ngclient-workflows(1), ngclient-features(1), transparent_recall(1), ngmigrate(1), ngrecall(1)

8.1.1.7. LICENSE

2021 ArcaPix Limited

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.