Accessing SMB file shares from Helix with rclone and Kerberos

Overview

Rclone can access an SMB/CIFS file share from Helix when the storage provider supports NIH Kerberos authentication. Kerberos lets rclone use a temporary credential ticket instead of storing your NIH password in the rclone configuration.

In this workflow, rclone runs on Helix and connects to the SMB server over the network. The name configured in rclone is a short label for that connection. A path has this form:

remote-name:share-name/path/within/share

The first component after the colon is the SMB share name. The remaining components identify a directory or file within that share.

Important: This procedure does not mount a filesystem. It does not require mount.cifs, a mount point, or sudo. Access the share with rclone commands such as lsd, lsf, and copy. Do not use rclone mount on Helix unless NIH HPC staff specifically directs you to do so.

Before you begin

Ask the group that manages the SMB server for the following information:

Confirmation that the server accepts Kerberos authentication from Helix.
The server's fully qualified DNS hostname, such as files.example.nih.gov. Do not include smb://, a share name, or a directory path. Do not use an IP address with Kerberos.
The SMB share name and any directory below it that you need to access.
Confirmation that your NIH account has permission to access the share.

The examples on this page use the following placeholders:

Values used in the examples
Placeholder	Replace with
`my-smb`	A short name that you choose for the rclone remote
`files.example.nih.gov`	The SMB server's fully qualified DNS hostname
`share-name`	The SMB share name supplied by its administrator
`path/to/data`	An optional path within that share

Get and manage a Kerberos ticket

Log in to Helix, load the rclone module, and request a ticket for your NIH principal. The Kerberos realm NIH.GOV is uppercase.

module load rclone
kinit "${USER}@NIH.GOV"

Enter your NIH password when prompted. The password is not displayed as you type. Do not put your NIH password in a command, script, or rclone configuration file.

View the ticket:

klist

Check the Default principal, Expires, and, when present, renew until fields. Expires is the end of the ticket's current validity. renew until is a separate deadline; it does not mean that the ticket remains continuously valid until that time. Ticket lifetimes are controlled by Kerberos policy, so always use the times shown by klist.

Before the current Expires time, renew a renewable ticket and verify its new expiration time:

kinit -R
klist

If renewal fails, the ticket has expired, or its renewable period has ended, run kinit "${USER}@NIH.GOV" again to obtain a new ticket.

Configure an SMB remote in rclone

Start the interactive configuration on Helix:

rclone config

Enter n to create a new remote. Use the responses below. Menu numbers can change between rclone versions, so enter the backend name smb instead of selecting it by number. If your rclone version displays other optional prompts, accept their defaults unless NIH HPC staff instruct you otherwise.

Recommended responses to the rclone configuration prompts
Prompt	Response	Explanation
`name>`	`my-smb`	Choose any short, descriptive remote name.
`Storage>`	`smb`	Select the SMB/CIFS backend by name.
`host>`	`files.example.nih.gov`	Enter only the administrator-provided hostname.
`user>`	Press Enter	Kerberos uses the principal in your credential cache.
`port>`	Press Enter	Use port 445 unless the administrator specifies another port.
`pass>`	`n`	Do not store your NIH password in rclone.
`domain>`	Press Enter	This setting is for NTLM; it does not set the Kerberos realm.
`use_kerberos>`	`true`	Authenticate using the Kerberos credential cache.
`Edit advanced config?`	`n`	Use the default advanced settings.
`Keep this "my-smb" remote?`	`y`	Save the remote.

At the main configuration menu, enter q to quit.

The remote name is only a label in your rclone configuration. With use_kerberos = true, the Kerberos identity and realm come from the credential cache created by kinit. The rclone domain setting is not the Kerberos realm.

List shares and files

If the server permits share enumeration, list the SMB shares visible to your account:

rclone lsd my-smb:

Some SMB servers do not permit share enumeration. You can instead test the share name supplied by its administrator directly. List only the first level of a share or directory:

rclone lsf --max-depth 1 "my-smb:share-name"
rclone lsf --max-depth 1 "my-smb:share-name/path with spaces"

Double quotes handle spaces and apostrophes in these examples. Follow your shell's quoting rules if a path contains other special characters. The rclone ls command lists files recursively and can produce a large amount of output, so use rclone lsf --max-depth 1 for an initial access test.

Copy data

After confirming the source and destination paths, preview a copy from the SMB share to an HPC directory with --dry-run:

rclone copy --dry-run --verbose --progress "my-smb:share-name/path/to/data" /data/$USER/destination

Review the proposed operation. If the source, destination, and files are correct, run the copy without --dry-run:

rclone copy --progress "my-smb:share-name/path/to/data" /data/$USER/destination

Reverse the source and destination to copy to an SMB share for which you have write permission:

rclone copy --dry-run --verbose --progress /data/$USER/source "my-smb:share-name/path/to/destination"
rclone copy --progress /data/$USER/source "my-smb:share-name/path/to/destination"

When the source is a directory, rclone copy copies the directory's contents, not the directory name itself. It can replace a different file at the same destination path, but it does not delete destination-only files. Be especially careful with rclone sync, which can delete destination files that are not present at the source.

For a long transfer, run klist before starting and make sure that the ticket has sufficient remaining validity. tmux, screen, and nohup can keep a process running after disconnection, but they do not renew Kerberos tickets. Do not assume that refreshing a ticket will seamlessly extend an already-running transfer. If a transfer reports an authentication error, renew or reacquire the ticket and rerun rclone copy; files already copied successfully and still unchanged are skipped.

These instructions are for an interactive session on Helix. Do not assume that an interactive Kerberos credential cache will be available to a Biowulf batch job.

Troubleshooting

Common rclone SMB and Kerberos problems
Symptom	What to check
Authentication or logon failure	Run `klist`. If the ticket is missing or expired, run `kinit "${USER}@NIH.GOV"`. Confirm that the default principal is your NIH account.
The server works with a password but not Kerberos	Ask the storage administrators whether Kerberos is enabled and supported from Helix.
Share or path not found	Run `rclone lsd my-smb:`. Verify that the first component after the colon is the share name.
Permission denied within a share	Ask the share owner to verify your access. Kerberos authenticates your identity but does not grant additional file permissions.
Connection timeout or refusal	Ask the storage administrators and NIH HPC staff to verify DNS, routing, firewall rules, and SMB access from Helix.

When contacting NIH HPC through an approved support channel, include the SMB hostname, share name, rclone command, and a sanitized error message. Redact internal identifiers before posting in a public forum. Never send your password or the contents of a Kerberos credential cache.