Admin.sh

This is documentation for the admin.sh system administration utility, which is part of the management infrastructure for Network v2.

Help

Usage: admin.sh [OPTION]... COMMAND [ARGS]...

This script conducts administrative functions specified by the COMMAND argument on hosts and databases on the network. For available options see the OPTION section below. The ARGS vary by command, see the relevant command in the COMMAND section.

COMMAND

go-online

go-online [HOST]...

Brings critical services on HOSTs online. Particularly useful to bring services back online after a 'backup-offline' command.

If specific hosts are not nominated the entire network is taken online.

Any salt-master can take any hosts online.

go-offline

go-offline [HOST]...

Takes critical services on HOSTs offline.

If specific hosts are not nominated the entire network is taken offline.

Any salt-master can take any hosts offline.

backup-online

backup-online [HOST]...

Conducts a quick-and-dirty backup of HOSTs without taking them offline. This is an unsafe operation and can result in inconsistent backups.

If specific hosts are not nominated the entire network is backed up.

Any salt-master can process backup commands for any host.

backup-offline

backup-offline [HOST]...

Conducts a backup of HOSTs after taking them offline, and leaves the HOSTs offline when finished. Offline backups should be consistent as services which can change files are stopped during the backup process.

If specific hosts are not nominated the entire network is taken offline and backed up.

Any salt-master can process backup commands for any host.

backup-safe

backup-safe [HOST]...

Conducts a backup of HOSTs after taking them offline, then brings them back online if there are no errors. Hosts may be left offline if the backup fails. Safe backups should be consistent as services which can change files are stopped during the backup process.

If specific hosts are not nominated the entire network is backed up.

Any salt-master can process backup commands for any host.

deploy

deploy TARGET [from SOURCE [ONLY]]

Deploys backups to TARGET. If specified, backups are deployed from SOURCE. If SOURCE is not specified the most recent TARGET backup is used as the source. If you want to limit the deployment to only one specific target directory specify that directory in ONLY.

Deployments are only done if the target directory does not already exist on the TARGET. If the backup has already been deployed it is not deployed again. If you want to force a deployment, see the 'restore' command.

A test salt-master can only deploy to test hosts (not production hosts).

restore

restore TARGET [from SOURCE [ONLY]]

Restores backups to TARGET. If specified, backups are restored from SOURCE. If SOURCE is not specified the most recent TARGET backup is used as the source. If you want to limit the restoration to only one specific target directory specify that directory in ONLY.

Restorations are always processed, even if the target directory already exists on the TARGET. If you don't want to force a restoration, see the 'deploy' command.

A test salt-master can only restore to test hosts (not production hosts).

migrate

migrate TARGET from LEGACY [ONLY]

Restores a legacy backup to TARGET. The legacy host to restore from must be specified as LEGACY. Particular targets can only be migrated from supported legacy backups. If you want to limit the migration to only one specific target directory, specify that directory in ONLY.

Migrations are always processed, even if the target directory already exists on the TARGET, so be careful!

A test salt-master can only migrate to test hosts (not production hosts).

backup-database

backup-database DBPART...

Backups up a live gen-2 database from the database server 'unity'. Specify the full database name, or nominate its parts, with the DBPART argument(s).

Any salt-master can process backups for any database.

restore-database

restore-database FILE to DBPART...

Restores a live gen-2 database to the database server 'unity'. The FILE argument nominates the input database backup file, you may need to run a database backup first with the 'database-backup' command (see above). Specify the full target database name, or nominates its parts, with the DBPART argument(s).

The target database must already exist on the database server 'unity' in order to be restored. The existing database will be replaced by the restore process. If you need to provision a new database, please see:

https://www.intranet.blackbrick.com/bbs/Network_v2#Provision_a_database

A test salt-master can only restore to test databases (starting with 'dbt__').

migrate-database

migrate-database LEGACY OLD_DB to DBPART...

Migrates a legacy gen-1 database to a gen-2 database on the database server 'unity'. The LEGACY argument nominates the gen-1 server the old database is on, and the OLD_DB is the name of the old database. Specify the full target database name, or nominates its parts, with the DBPART argument(s).

The target database must already exist on the database server 'unity' in order to be migrated. The existing database will be replaced by the migration process. If you need to provision a new database, please see:

https://www.intranet.blackbrick.com/bbs/Network_v2#Provision_a_database

A test salt-master can only migrate to test databases (starting with 'dbt__').

HOST

A HOST argument specifies a hostname for a host on the network. Test hosts, in the 'test' environment, have a hostname that ends with '-test'.

TARGET

A TARGET argument specifies a hostname for a host on the network that is to be the target for an operation. Production hosts cannot be targetted from a test salt-master. Test host are hosts in the 'test' environment, and their hostname ends with '-test'. A test salt-master is also in the 'test' environment, and its name also ends with '-test'.

SOURCE

A SOURCE argument specifies a hostname for the backup to be used for an operation. A suitable backup in the /data/backup/host/SOURCE/1/ directory must be available. Do a source backup first if necessary.

ONLY

An ONLY argument nominates a single target directory to be used in an operation. For example, if you only want to restore /srv/admin on the target, then specify that as the ONLY argument.

LEGACY

A LEGACY argument specifies a hostname for the backup to be used for a migration. The backup must be from a Generation 1 host, and particular targets can only be migrated from supported legacy backups. A suitable backup in the /data/backup/host/LEGACY/1/ directory must be available. Do a legacy backup first if necessary.

DBPART

A DBPART argument specifies a complete database name, or part thereof. A full database name is constructed by gluing the parts together with '__'. For information about the database naming conventions in use, please see:

https://www.intranet.blackbrick.com/bbs/Network_v2#Database_naming_conventions

FILE

A FILE argument specifies an input file for a database restore. If the file extension is .gz the input file is decompressed before use. The decompressed file must be an SQL file, typically created by the backup-database command (above).

OLD_DB

An OLD_DB argument is a database name for a legacy database on a legacy server.

OPTION

Program options are:

N/A

Global options are:

--debug           enable debug reporting (default).
--no-debug        disable debug reporting.
--mail            send email on error (default).
--no-mail         do not send email on error.
--status          enable status reporting (default).
--no-status       disable status reporting.
--interactive     run interactively (i.e. ask questions, this is the default).
--noninteractive  run noninteractively (i.e. use defaults or fail).
--quick           don't give opportunity to cancel.
--delay           delay before major operations to allow for Ctrl+C (default).

Copyright

Copyright © 2017, John Elliot V <jj5@jj5.net>. All rights reserved.

License

MIT License: <https://opensource.org/licenses/MIT>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Examples

For example, to take cooperation-test and forbearance-test offline:

# admin.sh go-offline cooperation-test forbearance-test

To take legacy ProgClub hosts offline:

# admin.sh go-offline hope honesty charity

To bring legacy ProgClub hosts back online:

# admin.sh go-online charity honesty hope

To make sure all hosts are online:

# admin.sh go-online

To do a quick-and-dirty (potentially inconsistent) backup of honesty and hope:

# admin.sh backup-online honesty hope

To do a safe (consistent) backup of charity and leave it offline:

# admin.sh backup-offline charity

To do a safe (consistent) backup of honesty and hope then bring back online:

# admin.sh backup-safe honesty hope

To do a first deployment of integrity-test from its production host's backup:

# admin.sh backup-safe integrity
# admin.sh deploy integrity-test from integrity

To force a restore to integrity-test from its production host's backup:

# admin.sh backup-safe integrity
# admin.sh restore integrity-test from integrity

To restore only production email from integrity to integrity-test:

# admin.sh backup-online integrity
# admin.sh restore integrity-test from integrity /var/vmail

To migrage the legacy ProgClub administration server charity to integrity:

# admin.sh backup-offline charity
# admin.sh migrate integrity from charity

To backup ProgClub's production email database:

# admin.sh backup-database prod pc-adm-1 postfix

To restore a production backup of ProgClub's email database to a test database:

# cd /data/backup/database/gen-2/dbp/pc_adm_1/postfix
# pushd "$( ls -td */ | head -n1 )" >/dev/null
# admin.sh restore-database dbp__pc_adm_1__postfix.sql.gz \
  test pc-adm-1 postfix

To migrate the legacy ProgClub email database into test for gen-2:

# admin.sh migrate-database charity postfix to test pc-adm-1 postfix

To migrate the legacy ProgClub email database into production for gen-2:

# admin.sh migrate-database charity postfix to prod pc-adm-1 postfix