2e1e76cbbeb97185159d53536be6aa07b8f43126
account_migration.md
| ... | ... | @@ -0,0 +1,190 @@ |
| 1 | +## Migrating existing accounts |
|
| 2 | + |
|
| 3 | +The sbgrid-cli feature allows a user to change accounts. This can be useful when moving between SBGrid member labs or to change from legacy SBGrid account to a new account which allows installation of BioGrids |
|
| 4 | + |
|
| 5 | +The process is does not require reinstallation or extensive changes to the filesystem. |
|
| 6 | +A network connection required and a recent release of `sbgrid-cli` is required. |
|
| 7 | + |
|
| 8 | +### sbgrid-cli migrate-account usage |
|
| 9 | +``` |
|
| 10 | + $ ./sbgrid-cli migrate-account --help |
|
| 11 | + |
|
| 12 | + SBGrid Installer 2.2.20 e4c704acc0 — |
|
| 13 | + _______ _____ _ __ |
|
| 14 | + / __/ _ )/ ___/___(_)__/ / |
|
| 15 | + _\ \/ _ / (_ / __/ / _ / |
|
| 16 | + /___/____/\___/_/ /_/\_,_/ |
|
| 17 | + C o n s o r t i u m |
|
| 18 | + |
|
| 19 | + USAGE — migrate-account |
|
| 20 | + |
|
| 21 | + ▸ sbgrid-cli migrate-account [site] [user] [key] [OPTIONS...] |
|
| 22 | + |
|
| 23 | + |
|
| 24 | + ARGUMENTS |
|
| 25 | + |
|
| 26 | + [site] The installation site provided with your new account |
|
| 27 | + credentials |
|
| 28 | + [user] The username provided with your new account credentials |
|
| 29 | + [key] The activation key provided with your new account |
|
| 30 | + credentials |
|
| 31 | + |
|
| 32 | + OPTIONS |
|
| 33 | + |
|
| 34 | + -c, --custom-config <config> Specify a custom configuration file (the new account |
|
| 35 | + credentials will be overwritten to the same location) |
|
| 36 | + --darwin Specify macOS as a platform |
|
| 37 | + --linux Specify Linux as a platform |
|
| 38 | + |
|
| 39 | + GLOBAL OPTIONS |
|
| 40 | + |
|
| 41 | + -h, --help Display global help or command-related help. |
|
| 42 | + -V, --version Display version. |
|
| 43 | + --no-color Disable use of colors in output. |
|
| 44 | + -v, --verbose Verbose mode: will also output debug messages. |
|
| 45 | + --quiet Quiet mode - only displays warn and error messages. |
|
| 46 | + --silent Silent mode: does not output anything, giving no |
|
| 47 | + indication of success or failure other than the exit |
|
| 48 | + code. |
|
| 49 | + -y, --yes Skips confirmation prompts |
|
| 50 | + --no-progress-bar Disables the progress bar |
|
| 51 | + |
|
| 52 | +``` |
|
| 53 | + |
|
| 54 | +The sbgrid-cli has a migration function to migrate between two SBGrid accounts. |
|
| 55 | +You only need to run three commands. In a terminal, run: |
|
| 56 | + |
|
| 57 | +1) Download the latest version of the sbgrid-cli with the curl command. You can also use a browser. |
|
| 58 | + |
|
| 59 | +On macOS : |
|
| 60 | +``` |
|
| 61 | + $ curl -k -LO https://sbgrid-installation-manager.s3.amazonaws.com/2.2.20/sbgrid-cli_2.2.20-macos.tar.gz |
|
| 62 | +``` |
|
| 63 | +On Linux: |
|
| 64 | +``` |
|
| 65 | + $ curl -k -LO https://sbgrid-installation-manager.s3.amazonaws.com/2.2.20/sbgrid-cli_2.2.20-linux.tar.gz |
|
| 66 | +``` |
|
| 67 | + |
|
| 68 | +1) Decompress and untar the archive |
|
| 69 | +``` |
|
| 70 | + $ tar -zxf sbgrid-cli_2.2.20-macos.tar.gz |
|
| 71 | +``` |
|
| 72 | + |
|
| 73 | +3) Run the migration command. The "./" preceding the command will execute the downloaded and decompressed file from the current directory. |
|
| 74 | +``` |
|
| 75 | + $ ./sbgrid-cli migrate-account |
|
| 76 | +``` |
|
| 77 | +You will be prompted for a new site, username, and key. |
|
| 78 | +``` |
|
| 79 | + $ ./sbgrid-cli migrate-account |
|
| 80 | +✔ Enter the new site name … smith_b_123i |
|
| 81 | +✔ Enter the new username … jdoe |
|
| 82 | +✔ Enter the new key … nPjmIsDZYD6060jSCReL5G73AeHPxCMhDRt4== |
|
| 83 | +``` |
|
| 84 | + |
|
| 85 | +or you can just use this command to do it all in one shot: |
|
| 86 | + |
|
| 87 | +``` |
|
| 88 | + $ ./sbgrid-cli migrate-account smith_b_123i jdoe nPjmIsDZYD6060jSCReL5G73AeHPxCMhDRt4== |
|
| 89 | +``` |
|
| 90 | + |
|
| 91 | +If all goes well, you should see : |
|
| 92 | + |
|
| 93 | +``` |
|
| 94 | +$ ./sbgrid-cli migrate-account smith_b_123i jdoe VJmj0xjVA1ovzbXjDEhfYhAqcAu9lnpopalT== |
|
| 95 | +info: Verifying the new credentials & running installation diagnostics... |
|
| 96 | +info: (1/3) Checking rsync credentials... |
|
| 97 | +info: (2/3) Checking connection... |
|
| 98 | +info: Checking services... |
|
| 99 | +info: Checking sbgrid.org (HTTPS) ... |
|
| 100 | +info: Checking sbgrid.org (HTTP) ... |
|
| 101 | +info: (3/3) Checking your installation's file permissions & ownership |
|
| 102 | +info: Checking file permissions... |
|
| 103 | +info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600 |
|
| 104 | +info: OK -> /home/jdoe/.sbgrid/logs has permissions 0755 |
|
| 105 | +info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600 |
|
| 106 | +info: OK -> /programs has permissions 0755 |
|
| 107 | +info: OK -> /opt/sbgrid has permissions 0755 |
|
| 108 | +info: Checking file ownership... |
|
| 109 | +info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer |
|
| 110 | +info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid/logs |
|
| 111 | +info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer |
|
| 112 | +info: OK -> user jdoe is the owner of the /programs |
|
| 113 | +info: OK -> user jdoe is the owner of the /opt/sbgrid |
|
| 114 | +info: Credential verification & installation diagnostics completed successfully |
|
| 115 | +✔ This command will now migrate your current installation to the new account credentials. |
|
| 116 | +Continue? … yes |
|
| 117 | +info: Retrieving package metadata... |
|
| 118 | +info: (1/1) Setting up your installation... |
|
| 119 | +info: Migration complete |
|
| 120 | +``` |
|
| 121 | + |
|
| 122 | +**Success!** |
|
| 123 | + |
|
| 124 | +## Troubleshooting some common errors |
|
| 125 | +### Authentication failed |
|
| 126 | +The following error means the new account credentials were incorrect or invalid. |
|
| 127 | +Check for typos or errors cutting and pasting. |
|
| 128 | + |
|
| 129 | +``` |
|
| 130 | +info: Verifying the new credentials & running installation diagnostics... |
|
| 131 | +info: Retrieving package metadata... |
|
| 132 | +info: (1/3) Checking rsync credentials... |
|
| 133 | + |
|
| 134 | +error: Authentication failed |
|
| 135 | + |
|
| 136 | +error: Credential verification failed for user: jdoe and site: smith_b_123i |
|
| 137 | +``` |
|
| 138 | + |
|
| 139 | +### Permissions and file ownership issue |
|
| 140 | + |
|
| 141 | +The installation must belong to user account doing the migration. |
|
| 142 | +The error below shows a failure due to ownership of /programs. To fix this, correct the file ownership, typically with the `chown` command. |
|
| 143 | + |
|
| 144 | +``` |
|
| 145 | + $ ./sbgrid-cli migrate-account |
|
| 146 | +✔ Enter the new site name … smith_b_123i |
|
| 147 | +✔ Enter the new username … jdoe |
|
| 148 | +✔ Enter the new key … nPjmIsDZYD6060jSCReL5G73AeHPxCMhDRt4== |
|
| 149 | +info: Verifying the new credentials & running installation diagnostics... |
|
| 150 | +info: (1/3) Checking rsync credentials... |
|
| 151 | +info: (2/3) Checking connection... |
|
| 152 | +info: Checking services... |
|
| 153 | +info: Checking sbgrid.org (HTTPS) ... |
|
| 154 | +info: Checking sbgrid.org (HTTP) ... |
|
| 155 | +info: (3/3) Checking your installation's file permissions & ownership |
|
| 156 | +info: Checking file permissions... |
|
| 157 | +info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600 |
|
| 158 | +info: OK -> /home/jdoe/.sbgrid/logs has permissions 0755 |
|
| 159 | +info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600 |
|
| 160 | +info: OK -> /programs has permissions 0755 |
|
| 161 | +info: OK -> /opt/sbgrid has permissions 0755 |
|
| 162 | +info: Checking file ownership... |
|
| 163 | +info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer |
|
| 164 | +info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid/logs |
|
| 165 | +info: OK -> user jdoe is the owner of the /home/jdoe/.sbgrid_installer |
|
| 166 | +**warn: BAD -> user with UID 2000 is the owner of the /programs** |
|
| 167 | +info: OK -> user jdoe is the owner of the /opt/sbgrid |
|
| 168 | + |
|
| 169 | +error: Permissions & ownership diagnostic failed |
|
| 170 | +``` |
|
| 171 | + |
|
| 172 | +### Missing programs link |
|
| 173 | + |
|
| 174 | +A symlink from /programs to the software installation directory is assumed to be present. If that link is missing the migration fails with this error. To fix this, (re)create the link at /programs. |
|
| 175 | +``` |
|
| 176 | + $ ./sbgrid-cli migrate-account smith_b_123i jdoe VJmj0xjVA1ovzbXjDEhfYhAqcAu9lnpopalT== |
|
| 177 | +info: Verifying the new credentials & running installation diagnostics... |
|
| 178 | +info: (1/3) Checking rsync credentials... |
|
| 179 | +info: (2/3) Checking connection... |
|
| 180 | +info: Checking services... |
|
| 181 | +info: Checking sbgrid.org (HTTPS) ... |
|
| 182 | +info: Checking sbgrid.org (HTTP) ... |
|
| 183 | +info: (3/3) Checking your installation's file permissions & ownership |
|
| 184 | +info: Checking file permissions... |
|
| 185 | +info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600 |
|
| 186 | +info: OK -> /home/jdoe/.sbgrid/logs has permissions 0755 |
|
| 187 | +info: OK -> /home/jdoe/.sbgrid_installer has permissions 0600 |
|
| 188 | + |
|
| 189 | +error: ENOENT: no such file or directory, stat '/programs' |
|
| 190 | +``` |
sbgrid-cli.md
| ... | ... | @@ -164,7 +164,7 @@ The sbgrid-cli feature allows a user to change accounts. This can be useful in a |
| 164 | 164 | |
| 165 | 165 | - Moving between SBGrid member labs |
| 166 | 166 | - To change the ownership of an existing installation |
| 167 | - - To change from legacy SBGrid account to a new account which allows installation of BioGrids |
|
| 167 | + - To change from legacy SBGrid account to a new account which allows installation of BioGrids [(migration guide here)](account_migration) |
|
| 168 | 168 | |
| 169 | 169 | The process is does not require reinstallation, downloading new software or extensive changes to the filesystem (and should be fast). |
| 170 | 170 |