Account Migration Guide
Managing SBGrid Installation Manager Accounts
SBGrid installation manager accounts come in two types, personal and site installations. Personal accounts have a user name, site name and a key while site installations only have a site and a key. The "site name" maps to an institutional installation profile that includes all software titles a site can access.
Occasionally, users move between groups or universities and it is necessary to "migrate" the account. The sbgrid-cli migrate-account command allows a user to change site affiliation without reinstallation of the software or changing user name and key.
To migrate an account, the user must be logged in as the account that "owns" the software collection on the computer (i.e. the same user who owns the POSIX permissions for all application files). A network connection is required.
sbgrid-cli migrate-account usage info
$ ./sbgrid-cli migrate-account --help
SBGrid Installer 2.11. e4c704acc0 —
_______ _____ _ __
/ __/ _ )/ ___/___(_)__/ /
_\ \/ _ / (_ / __/ / _ /
/___/____/\___/_/ /_/\_,_/
C o n s o r t i u m
USAGE — migrate-account
▸ sbgrid-cli migrate-account [site] [user] [key] [OPTIONS...]
ARGUMENTS
[site] The installation site provided with your new account
credentials
[user] The username provided with your new account credentials
[key] The activation key provided with your new account
credentials
OPTIONS
-c, --custom-config <config> Specify a custom configuration file (the new account
credentials will be overwritten to the same location)
--darwin Specify macOS as a platform
--linux Specify Linux as a platform
GLOBAL OPTIONS
-h, --help Display global help or command-related help.
-V, --version Display version.
--no-color Disable use of colors in output.
-v, --verbose Verbose mode: will also output debug messages.
--quiet Quiet mode - only displays warn and error messages.
--silent Silent mode: does not output anything, giving no
indication of success or failure other than the exit
code.
-y, --yes Skips confirmation prompts
--no-progress-bar Disables the progress bar
Easy migration in 3 steps
The SBGrid-cli has a migration function to migrate between two SBGrid accounts. The complete process can be completed with three terminal commands.
- Download the latest version of the sbgrid-cli with the curl command. You can also use a browser.
On macOS :
On Linux:
2) Decompress and untar the archive
On macOS :
On Linux:
3) Run the sbgrid-cli with the migrate-account subcommand. The "./" preceding the command will execute the downloaded and decompressed file from the current directory.
You will be prompted for your new site, username, and key.
$ ./sbgrid-cli migrate-account
✔ Enter the new site name … smith_b_123i
✔ Enter the new username … jdoe
✔ Enter the new key … nPjmIsDZYD6060jSCReL5G73AeHPxCMhDRt4==
You can migrate the account by providing the user, site, and key all in one command:
If all goes well, you should see :
$ ./sbgrid-cli migrate-account smith_b_123i jdoe VJmj0xjVA1ovzbXjDEhfYhAqcAu9lnpopalT==
info: Verifying the new credentials & running installation diagnostics...
info: (1/3) Checking rsync credentials...
info: (2/3) Checking connection...
info: Checking services...
info: Checking sbgrid.org (HTTPS) ...
info: Checking sbgrid.org (HTTP) ...
info: (3/3) Checking your installation's file permissions & ownership
info: Checking file permissions...
info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600
info: OK -> /home/jdoe/.sbgrid/logs has permissions 0755
info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600
info: OK -> /programs has permissions 0755
info: OK -> /opt/sbgrid has permissions 0755
info: Checking file ownership...
info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer
info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid/logs
info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer
info: OK -> user jdoe is the owner of the /programs
info: OK -> user jdoe is the owner of the /opt/sbgrid
info: Credential verification & installation diagnostics completed successfully
✔ This command will now migrate your current installation to the new account credentials.
Continue? … yes
info: Retrieving package metadata...
info: (1/1) Setting up your installation...
info: Migration complete
Success!
Troubleshooting common account migration errors
Authentication failed
The following error means the new account credentials were incorrect or invalid. Check for typos or errors cutting and pasting.
info: Verifying the new credentials & running installation diagnostics...
info: Retrieving package metadata...
info: (1/3) Checking rsync credentials...
error: Authentication failed
error: Credential verification failed for user: jdoe and site: smith_b_123i
Permissions and file ownership issue
The installation must belong to user account doing the migration.
The error below shows a failure due to file permissions, specifically the incorrect ownership of /programs. To fix this, correct the file ownership, typically with the chown command.
$ ./sbgrid-cli migrate-account
✔ Enter the new site name … smith_b_123i
✔ Enter the new username … jdoe
✔ Enter the new key … nPjmIsDZYD6060jSCReL5G73AeHPxCMhDRt4==
info: Verifying the new credentials & running installation diagnostics...
info: (1/3) Checking rsync credentials...
info: (2/3) Checking connection...
info: Checking services...
info: Checking sbgrid.org (HTTPS) ...
info: Checking sbgrid.org (HTTP) ...
info: (3/3) Checking your installation's file permissions & ownership
info: Checking file permissions...
info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600
info: OK -> /home/jdoe/.sbgrid/logs has permissions 0755
info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600
info: OK -> /programs has permissions 0755
info: OK -> /opt/sbgrid has permissions 0755
info: Checking file ownership...
info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer
info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid/logs
info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer
**warn: BAD -> user with UID 2000 is the owner of the /programs**
info: OK -> user jdoe is the owner of the /opt/sbgrid
error: Permissions & ownership diagnostic failed
Missing programs link
A symlink from /programs to the software installation directory is required. If that link is missing, the migration fails with this error. To fix this, (re)create the link at /programs.
$ ./sbgrid-cli migrate-account smith_b_123i jdoe VJmj0xjVA1ovzbXjDEhfYhAqcAu9lnpopalT==
info: Verifying the new credentials & running installation diagnostics...
info: (1/3) Checking rsync credentials...
info: (2/3) Checking connection...
info: Checking services...
info: Checking sbgrid.org (HTTPS) ...
info: Checking sbgrid.org (HTTP) ...
info: (3/3) Checking your installation's file permissions & ownership
info: Checking file permissions...
info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600
info: OK -> /home/jdoe/.sbgrid/logs has permissions 0755
info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600
error: ENOENT: no such file or directory, stat '/programs'