From c05b79625fbbb61515ff4b75412653809fb4a677 Mon Sep 17 00:00:00 2001 From: Cai Hui Date: Sat, 13 Oct 2018 21:03:40 -0400 Subject: [PATCH] Update freezerclient documentation Change-Id: I2a36243847d8cbe02db7e99ba7c0995917204167 Story: 1706166 Task: 25709 --- doc/source/cli/details.rst | 805 +++++++++++++++++++++++++++ doc/source/cli/freezer.rst | 84 +++ doc/source/cli/index.rst | 841 +---------------------------- doc/source/contributor/index.rst | 17 + doc/source/contributor/testing.rst | 30 + doc/source/index.rst | 3 + doc/source/reference/index.rst | 41 ++ doc/source/user/index.rst | 6 + doc/source/user/shell.rst | 86 +++ 9 files changed, 1094 insertions(+), 819 deletions(-) create mode 100644 doc/source/cli/details.rst create mode 100644 doc/source/cli/freezer.rst create mode 100644 doc/source/contributor/index.rst create mode 100644 doc/source/contributor/testing.rst create mode 100644 doc/source/reference/index.rst create mode 100644 doc/source/user/index.rst create mode 100644 doc/source/user/shell.rst diff --git a/doc/source/cli/details.rst b/doc/source/cli/details.rst new file mode 100644 index 0000000..21f4b1b --- /dev/null +++ b/doc/source/cli/details.rst @@ -0,0 +1,805 @@ +============================================================================ +Backup, Restore, and Disaster Recovery service (freezer) command-line client +============================================================================ + +The freezer client is the command-line interface (CLI) for the +Backup, Restore, and Disaster Recovery service (freezer) API +and its extensions. + +This chapter documents :command:`freezer` version ``1.7.1``. + +For help on a specific :command:`freezer` command, enter: + +.. code-block:: console + + $ freezer help COMMAND + +.. _freezer_command_usage: + +freezer usage +~~~~~~~~~~~~~ + +.. code-block:: console + + usage: freezer [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug] + [--os-auth-url OS_AUTH_URL] [--os-backup-url OS_BACKUP_URL] + [--os-backup-api-version OS_BACKUP_API_VERSION] + [--os-endpoint-type OS_ENDPOINT_TYPE] + [--os-identity-api-version OS_IDENTITY_API_VERSION] + [--os-password OS_PASSWORD] [--os-username OS_USERNAME] + [--os-token OS_TOKEN] + [--os-project-domain-name OS_PROJECT_DOMAIN_NAME] + [--os-project-domain-id OS_PROJECT_DOMAIN_ID] + [--os-project-name OS_PROJECT_NAME] + [--os-region-name OS_REGION_NAME] + [--os-project-id OS_PROJECT_ID] + [--os-user-domain-name OS_USER_DOMAIN_NAME] + [--os-user-domain-id OS_USER_DOMAIN_ID] [-k] + [--os-cacert OS_CACERT] [--os-cert OS_CERT] + +.. _freezer_command_options: + +freezer optional arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``--version`` + show program's version number and exit + +``-v, --verbose`` + Increase verbosity of output. Can be repeated. + +``-q, --quiet`` + Suppress output except warnings and errors. + +``--log-file LOG_FILE`` + Specify a file to log output. Disabled by default. + +``-h, --help`` + Show help message and exit. + +``--debug`` + Show tracebacks on errors. + +``--os-auth-url OS_AUTH_URL`` + Specify identity endpoint + +``--os-backup-url OS_BACKUP_URL`` + Specify the Freezer backup service endpoint to use + +``--os-backup-api-version OS_BACKUP_API_VERSION`` + Backup API version: 1 or 2 + +``--os-endpoint-type OS_ENDPOINT_TYPE`` + Endpoint type to select. Valid endpoint types: + "public" or "publicURL", "internal" or "internalURL", + "admin" or "adminURL" + +``--os-identity-api-version OS_IDENTITY_API_VERSION`` + Identity API version: 2.0 or 3 + +``--os-password OS_PASSWORD`` + Password used for authentication with the OpenStack + Identity service + +``--os-username OS_USERNAME`` + Name used for authentication with the OpenStack + Identity service + +``--os-token OS_TOKEN`` + Specify an existing token to use instead of retrieving + one via authentication + +``--os-project-domain-name OS_PROJECT_DOMAIN_NAME`` + Domain name containing project + +``--os-project-domain-id OS_PROJECT_DOMAIN_ID`` + OpenStack project domain ID. Defaults to + ``env[OS_PROJECT_ID]``. + +``--os-project-name OS_PROJECT_NAME`` + Project name to scope to + +``--os-region-name OS_REGION_NAME`` + Specify the region to use + +``--os-project-id OS_PROJECT_ID`` + Project to request authorization on + +``--os-user-domain-name OS_USER_DOMAIN_NAME`` + User domain name + +``--os-user-domain-id OS_USER_DOMAIN_ID`` + OpenStack user domain ID. Defaults to + ``env[OS_USER_DOMAIN_ID]``. + +``-k, --insecure`` + use python-freezerclient with insecure connections + +``--os-cacert OS_CACERT`` + Path of CA TLS certificate(s) used to verify the + remote server's certificate. Without this option + freezer looks for the default system CA certificates. + +``--os-cert OS_CERT`` + Path of CERT TLS certificate(s) used to verify the + remote server's certificate.1 + +.. _freezer_action-create: + +freezer action-create +--------------------- + +.. code-block:: console + + usage: freezer action-create [-h] --file FILE + +Create an action from a file + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--file FILE`` + Path to json file with the action + +.. _freezer_action-delete: + +freezer action-delete +--------------------- + +.. code-block:: console + + usage: freezer action-delete [-h] action_id + +Delete an action from the api + +**Positional arguments:** + +``action_id`` + ID of the action + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_action-list: + +freezer action-list +------------------- + +.. code-block:: console + + usage: freezer action-list [-h] [-f {csv,html,json,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] + [--quote {all,minimal,none,nonnumeric}] + [--limit LIMIT] [--offset OFFSET] [--search SEARCH] + +List all actions for your user + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--limit LIMIT`` + Specify a limit for search query + +``--offset OFFSET`` + +``--search SEARCH`` + Define a filter for the query + +.. _freezer_action-show: + +freezer action-show +------------------- + +.. code-block:: console + + usage: freezer action-show [-h] [-f {html,json,shell,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] [--prefix PREFIX] + action_id + +Show a single action + +**Positional arguments:** + +``action_id`` + ID of the action + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_action-update: + +freezer action-update +--------------------- + +.. code-block:: console + + usage: freezer action-update [-h] action_id file + +Update an action from a file + +**Positional arguments:** + +``action_id`` + ID of the session + +``file`` + Path to json file with the action + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_backup-delete: + +freezer backup-delete +--------------------- + +.. code-block:: console + + usage: freezer backup-delete [-h] backup_uuid + +Delete a backup from the api + +**Positional arguments:** + +``backup_uuid`` + UUID of the backup + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_backup-list: + +freezer backup-list +------------------- + +.. code-block:: console + + usage: freezer backup-list [-h] [-f {csv,html,json,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] + [--quote {all,minimal,none,nonnumeric}] + [--limit LIMIT] [--offset OFFSET] [--search SEARCH] + +List all backups for your user + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--limit LIMIT`` + Specify a limit for search query + +``--offset OFFSET`` + +``--search SEARCH`` + Define a filter for the query + +.. _freezer_backup-show: + +freezer backup-show +------------------- + +.. code-block:: console + + usage: freezer backup-show [-h] [-f {html,json,shell,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] [--prefix PREFIX] + backup_uuid + +Show the metadata of a single backup + +**Positional arguments:** + +``backup_uuid`` + ID of the backup + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_client-delete: + +freezer client-delete +--------------------- + +.. code-block:: console + + usage: freezer client-delete [-h] client_id + +Delete a client from the api + +**Positional arguments:** + +``client_id`` + ID of the client + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_client-list: + +freezer client-list +------------------- + +.. code-block:: console + + usage: freezer client-list [-h] [-f {csv,html,json,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] + [--quote {all,minimal,none,nonnumeric}] + [--limit LIMIT] [--offset OFFSET] [--search SEARCH] + +List of clients registered in the api + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--limit LIMIT`` + Specify a limit for search query + +``--offset OFFSET`` + +``--search SEARCH`` + Define a filter for the query + +.. _freezer_client-register: + +freezer client-register +----------------------- + +.. code-block:: console + + usage: freezer client-register [-h] --file FILE + +Register a new client + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--file FILE`` + Path to json file with the client + +.. _freezer_client-show: + +freezer client-show +------------------- + +.. code-block:: console + + usage: freezer client-show [-h] [-f {html,json,shell,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] [--prefix PREFIX] + client_id + +Show a single client + +**Positional arguments:** + +``client_id`` + ID of the client + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_job-abort: + +freezer job-abort +----------------- + +.. code-block:: console + + usage: freezer job-abort [-h] job_id + +Abort a running job + +**Positional arguments:** + +``job_id`` + ID of the job + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_job-create: + +freezer job-create +------------------ + +.. code-block:: console + + usage: freezer job-create [-h] --file FILE --client CLIENT_ID + +Create a new job from a file + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--file FILE`` + Path to json file with the job + +``--client CLIENT_ID, -C`` + CLIENT_ID + Select a client for this job + +.. _freezer_job-delete: + +freezer job-delete +------------------ + +.. code-block:: console + + usage: freezer job-delete [-h] job_id + +Delete a job from the api + +**Positional arguments:** + +``job_id`` + ID of the job + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_job-get: + +freezer job-get +--------------- + +.. code-block:: console + + usage: freezer job-get [-h] [--no-format] job_id + +Download a job as a json file + +**Positional arguments:** + +``job_id`` + ID of the job + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--no-format`` + Return a job in json without pretty print + +.. _freezer_job-list: + +freezer job-list +---------------- + +.. code-block:: console + + usage: freezer job-list [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] + [--max-width ] [--fit-width] [--print-empty] + [--noindent] [--quote {all,minimal,none,nonnumeric}] + [--limit LIMIT] [--offset OFFSET] [--search SEARCH] + [--client CLIENT_ID] + +List all the jobs for your user + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--limit LIMIT`` + Specify a limit for search query + +``--offset OFFSET`` + +``--search SEARCH`` + Define a filter for the query + +``--client CLIENT_ID, -C`` + CLIENT_ID + Get jobs for a specific client + +.. _freezer_job-show: + +freezer job-show +---------------- + +.. code-block:: console + + usage: freezer job-show [-h] [-f {html,json,shell,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] [--prefix PREFIX] + job_id + +Show a single job + +**Positional arguments:** + +``job_id`` + ID of the job + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_job-start: + +freezer job-start +----------------- + +.. code-block:: console + + usage: freezer job-start [-h] job_id + +Send a start signal for a job + +**Positional arguments:** + +``job_id`` + ID of the job + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_job-stop: + +freezer job-stop +---------------- + +.. code-block:: console + + usage: freezer job-stop [-h] job_id + +Send a stop signal for a job + +**Positional arguments:** + +``job_id`` + ID of the job + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_job-update: + +freezer job-update +------------------ + +.. code-block:: console + + usage: freezer job-update [-h] job_id file + +Update a job from a file + +**Positional arguments:** + +``job_id`` + ID of the job + +``file`` + Path to json file with the job + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_session-add-job: + +freezer session-add-job +----------------------- + +.. code-block:: console + + usage: freezer session-add-job [-h] --session-id SESSION_ID --job-id JOB_ID + +Add a job to a session + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--session-id SESSION_ID`` + ID of the session + +``--job-id JOB_ID`` + ID of the job to add + +.. _freezer_session-create: + +freezer session-create +---------------------- + +.. code-block:: console + + usage: freezer session-create [-h] --file FILE + +Create a session from a file + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--file FILE`` + Path to json file with the job + +.. _freezer_session-delete: + +freezer session-delete +---------------------- + +.. code-block:: console + + usage: freezer session-delete [-h] session_id + +Delete a session + +**Positional arguments:** + +``session_id`` + ID of the session + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_session-list: + +freezer session-list +-------------------- + +.. code-block:: console + + usage: freezer session-list [-h] [-f {csv,html,json,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] + [--quote {all,minimal,none,nonnumeric}] + [--limit LIMIT] [--offset OFFSET] + [--search SEARCH] + +List all the sessions for your user + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--limit LIMIT`` + Specify a limit for search query + +``--offset OFFSET`` + +``--search SEARCH`` + Define a filter for the query + +.. _freezer_session-remove-job: + +freezer session-remove-job +-------------------------- + +.. code-block:: console + + usage: freezer session-remove-job [-h] --session-id SESSION_ID --job-id JOB_ID + +Remove a job from a session + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--session-id SESSION_ID`` + ID of the session + +``--job-id JOB_ID`` + ID of the job to add + +.. _freezer_session-show: + +freezer session-show +-------------------- + +.. code-block:: console + + usage: freezer session-show [-h] [-f {html,json,shell,table,value,yaml}] + [-c COLUMN] [--max-width ] [--fit-width] + [--print-empty] [--noindent] [--prefix PREFIX] + session_id + +Show a single session + +**Positional arguments:** + +``session_id`` + ID of the session + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +.. _freezer_session-start: + +freezer session-start +--------------------- + +.. code-block:: console + + usage: freezer session-start [-h] --session-id SESSION_ID --job-id JOB_ID + --job-tag JOB_TAG + +Start a session + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + +``--session-id SESSION_ID`` + ID of the session + +``--job-id JOB_ID`` + ID of the job + +``--job-tag JOB_TAG`` + Job tag value + +.. _freezer_session-update: + +freezer session-update +---------------------- + +.. code-block:: console + + usage: freezer session-update [-h] session_id file + +Update a session from a file + +**Positional arguments:** + +``session_id`` + ID of the session + +``file`` + Path to json file with the session + +**Optional arguments:** + +``-h, --help`` + show this help message and exit + diff --git a/doc/source/cli/freezer.rst b/doc/source/cli/freezer.rst new file mode 100644 index 0000000..02512e2 --- /dev/null +++ b/doc/source/cli/freezer.rst @@ -0,0 +1,84 @@ +================================ +:program:`freezer` CLI man page +================================ + +.. program:: freezer +.. highlight:: bash + +SYNOPSIS +======== + +:program:`freezer` [options] [command-options] + +:program:`freezer help` + +:program:`freezer help` + + +DESCRIPTION +=========== + +The :program:`freezer` command line utility interacts with OpenStack Backup, Restore, and DR service (Freezer). + +In order to use the CLI, you must provide your OpenStack username, password, +project (historically called tenant), and auth endpoint. You can use +configuration options ``--os-username``, ``--os-password``, ``--os-project-id``, +and ``--os-auth-url`` or set corresponding environment variables:: + + export OS_USERNAME=user + export OS_PASSWORD=pass + export OS_PROJECT_ID=c373706f891f48019483f8bd6503c54b + export OS_AUTH_URL=http://auth.example.com:5000/v2.0 + +The command line tool will attempt to reauthenticate using provided credentials +for every request. You can override this behavior by manually supplying an auth +token using ``--os-backup-url`` and ``--os-auth-token`` or by setting +corresponding environment variables:: + + export OS_IMAGE_URL=http://freezer.example.org:9090/ + export OS_AUTH_TOKEN=3bdc4d3a03f44e3d8377fa247b0ad155 + +You can select an API version to use by ``--os-backup-api-version`` option or by +setting corresponding environment variable:: + + export OS_BACKUP_API_VERSION=1 + +Default Freezer API used is v2. + +OPTIONS +======= + +To get a list of available commands and options run:: + + freezer help + +To get usage and options of a command:: + + freezer help + + +EXAMPLES +======== + +Get information about job-create command:: + + freezer help job-create + +See available actions:: + + freezer job-list + +Create new job:: + + freezer job-create --file /root/action-local-nova-with-vol.json --client + ubuntu_c89bd80e25da4407a12bfc73daa47052 + +Describe a specific image:: + + freezer job-show + +BUGS +==== + +Use the master OpenStack bug tracker,available at: +https://storyboard.openstack.org/#!/project/openstack/freezer. diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index 76a1758..da90794 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -1,826 +1,29 @@ -.. ################################################### -.. ## WARNING ###################################### -.. ############## WARNING ########################## -.. ########################## WARNING ############## -.. ###################################### WARNING ## -.. ################################################### -.. ################################################### -.. ## -.. This file is tool-generated. Do not edit manually. -.. http://docs.openstack.org/contributor-guide/ -.. doc-tools/cli-reference.html -.. ## -.. ## WARNING ###################################### -.. ############## WARNING ########################## -.. ########################## WARNING ############## -.. ###################################### WARNING ## -.. ################################################### +Command-line Tool Reference -============================================================================ -Backup, Restore, and Disaster Recovery service (freezer) command-line client -============================================================================ +In order to use the CLI, you must provide your OpenStack username, +password, tenant, and auth endpoint. Use the corresponding +configuration options (``--os-username``, ``--os-password``, +``--os-project-id``, and ``--os-auth-url``) or set them in environment +variables:: -The freezer client is the command-line interface (CLI) for the -Backup, Restore, and Disaster Recovery service (freezer) API -and its extensions. + export OS_USERNAME=user + export OS_PASSWORD=pass + export OS_PROJECT_ID=c373706f891f48019483f8bd6503c54b + export OS_AUTH_URL=http://auth.example.com:5000/v2.0 -This chapter documents :command:`freezer` version ``1.5.0``. +The command line tool will attempt to reauthenticate using your +provided credentials for every request. You can override this behavior +by manually supplying an auth token using ``--os-backup-url`` and +``--os-auth-token``. You can alternatively set these environment +variables:: -For help on a specific :command:`freezer` command, enter: + export OS_BACKUP_URL=http://freezer.example.org:9090/ + export OS_AUTH_TOKEN=3bdc4d3a03f44e3d8377fa247b0ad155 -.. code-block:: console +Once you've configured your authentication parameters, you can run +``freezer help`` to see a complete listing of available commands. - $ freezer help COMMAND - -.. _freezer_command_usage: - -freezer usage -~~~~~~~~~~~~~ - -.. code-block:: console - - usage: freezer [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug] - [--os-auth-url OS_AUTH_URL] [--os-backup-url OS_BACKUP_URL] - [--os-endpoint-type OS_ENDPOINT_TYPE] - [--os-identity-api-version OS_IDENTITY_API_VERSION] - [--os-password OS_PASSWORD] [--os-username OS_USERNAME] - [--os-token OS_TOKEN] - [--os-project-domain-name OS_PROJECT_DOMAIN_NAME] - [--os-project-domain-id OS_PROJECT_DOMAIN_ID] - [--os-project-name OS_PROJECT_NAME] - [--os-region-name OS_REGION_NAME] [--os-tenant-id OS_TENANT_ID] - [--os-project-id OS_PROJECT_ID] - [--os-tenant-name OS_TENANT_NAME] - [--os-user-domain-name OS_USER_DOMAIN_NAME] - [--os-user-domain-id OS_USER_DOMAIN_ID] [-k] - [--os-cacert OS_CACERT] [--os-cert OS_CERT] - -.. _freezer_command_options: - -freezer optional arguments -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``--version`` - show program's version number and exit - -``-v, --verbose`` - Increase verbosity of output. Can be repeated. - -``-q, --quiet`` - Suppress output except warnings and errors. - -``--log-file LOG_FILE`` - Specify a file to log output. Disabled by default. - -``-h, --help`` - Show help message and exit. - -``--debug`` - Show tracebacks on errors. - -``--os-auth-url OS_AUTH_URL`` - Specify identity endpoint - -``--os-backup-url OS_BACKUP_URL`` - Specify the Freezer backup service endpoint to use - -``--os-endpoint-type OS_ENDPOINT_TYPE`` - Endpoint type to select. Valid endpoint types: - "public" or "publicURL", "internal" or "internalURL", - "admin" or "adminURL" - -``--os-identity-api-version OS_IDENTITY_API_VERSION`` - Identity API version: 2.0 or 3 - -``--os-password OS_PASSWORD`` - Password used for authentication with the OpenStack - Identity service - -``--os-username OS_USERNAME`` - Name used for authentication with the OpenStack - Identity service - -``--os-token OS_TOKEN`` - Specify an existing token to use instead of retrieving - one via authentication - -``--os-project-domain-name OS_PROJECT_DOMAIN_NAME`` - Domain name containing project - -``--os-project-domain-id OS_PROJECT_DOMAIN_ID`` - OpenStack project domain ID. Defaults to - ``env[OS_PROJECT_ID]``. - -``--os-project-name OS_PROJECT_NAME`` - Project name to scope to - -``--os-region-name OS_REGION_NAME`` - Specify the region to use - -``--os-tenant-id OS_TENANT_ID`` - Tenant to request authorization on - -``--os-project-id OS_PROJECT_ID`` - Project to request authorization on - -``--os-tenant-name OS_TENANT_NAME`` - Tenant to request authorization on - -``--os-user-domain-name OS_USER_DOMAIN_NAME`` - User domain name - -``--os-user-domain-id OS_USER_DOMAIN_ID`` - OpenStack user domain ID. Defaults to - ``env[OS_USER_DOMAIN_ID]``. - -``-k, --insecure`` - use python-freezerclient with insecure connections - -``--os-cacert OS_CACERT`` - Path of CA TLS certificate(s) used to verify the - remote server's certificate. Without this option - freezer looks for the default system CA certificates. - -``--os-cert OS_CERT`` - Path of CERT TLS certificate(s) used to verify the - remote server's certificate.1 - -.. _freezer_action-create: - -freezer action-create ---------------------- - -.. code-block:: console - - usage: freezer action-create [-h] --file FILE - -Create an action from a file - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--file FILE`` - Path to json file with the action - -.. _freezer_action-delete: - -freezer action-delete ---------------------- - -.. code-block:: console - - usage: freezer action-delete [-h] action_id - -Delete an action from the api - -**Positional arguments:** - -``action_id`` - ID of the action - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_action-list: - -freezer action-list -------------------- - -.. code-block:: console - - usage: freezer action-list [-h] [-f {csv,html,json,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] - [--quote {all,minimal,none,nonnumeric}] - [--limit LIMIT] [--offset OFFSET] [--search SEARCH] - -List all actions for your user - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--limit LIMIT`` - Specify a limit for search query - -``--offset OFFSET`` - -``--search SEARCH`` - Define a filter for the query - -.. _freezer_action-show: - -freezer action-show -------------------- - -.. code-block:: console - - usage: freezer action-show [-h] [-f {html,json,shell,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] [--prefix PREFIX] - action_id - -Show a single action - -**Positional arguments:** - -``action_id`` - ID of the action - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_action-update: - -freezer action-update ---------------------- - -.. code-block:: console - - usage: freezer action-update [-h] action_id file - -Update an action from a file - -**Positional arguments:** - -``action_id`` - ID of the session - -``file`` - Path to json file with the action - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_backup-delete: - -freezer backup-delete ---------------------- - -.. code-block:: console - - usage: freezer backup-delete [-h] backup_uuid - -Delete a backup from the api - -**Positional arguments:** - -``backup_uuid`` - UUID of the backup - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_backup-list: - -freezer backup-list -------------------- - -.. code-block:: console - - usage: freezer backup-list [-h] [-f {csv,html,json,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] - [--quote {all,minimal,none,nonnumeric}] - [--limit LIMIT] [--offset OFFSET] [--search SEARCH] - -List all backups for your user - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--limit LIMIT`` - Specify a limit for search query - -``--offset OFFSET`` - -``--search SEARCH`` - Define a filter for the query - -.. _freezer_backup-show: - -freezer backup-show -------------------- - -.. code-block:: console - - usage: freezer backup-show [-h] [-f {html,json,shell,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] [--prefix PREFIX] - backup_uuid - -Show the metadata of a single backup - -**Positional arguments:** - -``backup_uuid`` - ID of the backup - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_client-delete: - -freezer client-delete ---------------------- - -.. code-block:: console - - usage: freezer client-delete [-h] client_id - -Delete a client from the api - -**Positional arguments:** - -``client_id`` - ID of the client - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_client-list: - -freezer client-list -------------------- - -.. code-block:: console - - usage: freezer client-list [-h] [-f {csv,html,json,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] - [--quote {all,minimal,none,nonnumeric}] - [--limit LIMIT] [--offset OFFSET] [--search SEARCH] - -List of clients registered in the api - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--limit LIMIT`` - Specify a limit for search query - -``--offset OFFSET`` - -``--search SEARCH`` - Define a filter for the query - -.. _freezer_client-register: - -freezer client-register ------------------------ - -.. code-block:: console - - usage: freezer client-register [-h] --file FILE - -Register a new client - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--file FILE`` - Path to json file with the client - -.. _freezer_client-show: - -freezer client-show -------------------- - -.. code-block:: console - - usage: freezer client-show [-h] [-f {html,json,shell,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] [--prefix PREFIX] - client_id - -Show a single client - -**Positional arguments:** - -``client_id`` - ID of the client - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_job-abort: - -freezer job-abort ------------------ - -.. code-block:: console - - usage: freezer job-abort [-h] job_id - -Abort a running job - -**Positional arguments:** - -``job_id`` - ID of the job - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_job-create: - -freezer job-create ------------------- - -.. code-block:: console - - usage: freezer job-create [-h] --file FILE --client CLIENT_ID - -Create a new job from a file - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--file FILE`` - Path to json file with the job - -``--client CLIENT_ID, -C`` - CLIENT_ID - Select a client for this job - -.. _freezer_job-delete: - -freezer job-delete ------------------- - -.. code-block:: console - - usage: freezer job-delete [-h] job_id - -Delete a job from the api - -**Positional arguments:** - -``job_id`` - ID of the job - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_job-get: - -freezer job-get ---------------- - -.. code-block:: console - - usage: freezer job-get [-h] [--no-format] job_id - -Download a job as a json file - -**Positional arguments:** - -``job_id`` - ID of the job - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--no-format`` - Return a job in json without pretty print - -.. _freezer_job-list: - -freezer job-list ----------------- - -.. code-block:: console - - usage: freezer job-list [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] - [--max-width ] [--fit-width] [--print-empty] - [--noindent] [--quote {all,minimal,none,nonnumeric}] - [--limit LIMIT] [--offset OFFSET] [--search SEARCH] - [--client CLIENT_ID] - -List all the jobs for your user - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--limit LIMIT`` - Specify a limit for search query - -``--offset OFFSET`` - -``--search SEARCH`` - Define a filter for the query - -``--client CLIENT_ID, -C`` - CLIENT_ID - Get jobs for a specific client - -.. _freezer_job-show: - -freezer job-show ----------------- - -.. code-block:: console - - usage: freezer job-show [-h] [-f {html,json,shell,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] [--prefix PREFIX] - job_id - -Show a single job - -**Positional arguments:** - -``job_id`` - ID of the job - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_job-start: - -freezer job-start ------------------ - -.. code-block:: console - - usage: freezer job-start [-h] job_id - -Send a start signal for a job - -**Positional arguments:** - -``job_id`` - ID of the job - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_job-stop: - -freezer job-stop ----------------- - -.. code-block:: console - - usage: freezer job-stop [-h] job_id - -Send a stop signal for a job - -**Positional arguments:** - -``job_id`` - ID of the job - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_job-update: - -freezer job-update ------------------- - -.. code-block:: console - - usage: freezer job-update [-h] job_id file - -Update a job from a file - -**Positional arguments:** - -``job_id`` - ID of the job - -``file`` - Path to json file with the job - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_session-add-job: - -freezer session-add-job ------------------------ - -.. code-block:: console - - usage: freezer session-add-job [-h] --session-id SESSION_ID --job-id JOB_ID - -Add a job to a session - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--session-id SESSION_ID`` - ID of the session - -``--job-id JOB_ID`` - ID of the job to add - -.. _freezer_session-create: - -freezer session-create ----------------------- - -.. code-block:: console - - usage: freezer session-create [-h] --file FILE - -Create a session from a file - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--file FILE`` - Path to json file with the job - -.. _freezer_session-delete: - -freezer session-delete ----------------------- - -.. code-block:: console - - usage: freezer session-delete [-h] session_id - -Delete a session - -**Positional arguments:** - -``session_id`` - ID of the session - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_session-list: - -freezer session-list --------------------- - -.. code-block:: console - - usage: freezer session-list [-h] [-f {csv,html,json,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] - [--quote {all,minimal,none,nonnumeric}] - [--limit LIMIT] [--offset OFFSET] - [--search SEARCH] - -List all the sessions for your user - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--limit LIMIT`` - Specify a limit for search query - -``--offset OFFSET`` - -``--search SEARCH`` - Define a filter for the query - -.. _freezer_session-remove-job: - -freezer session-remove-job --------------------------- - -.. code-block:: console - - usage: freezer session-remove-job [-h] --session-id SESSION_ID --job-id JOB_ID - -Remove a job from a session - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--session-id SESSION_ID`` - ID of the session - -``--job-id JOB_ID`` - ID of the job to add - -.. _freezer_session-show: - -freezer session-show --------------------- - -.. code-block:: console - - usage: freezer session-show [-h] [-f {html,json,shell,table,value,yaml}] - [-c COLUMN] [--max-width ] [--fit-width] - [--print-empty] [--noindent] [--prefix PREFIX] - session_id - -Show a single session - -**Positional arguments:** - -``session_id`` - ID of the session - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -.. _freezer_session-start: - -freezer session-start ---------------------- - -.. code-block:: console - - usage: freezer session-start [-h] --session-id SESSION_ID --job-id JOB_ID - --job-tag JOB_TAG - -Start a session - -**Optional arguments:** - -``-h, --help`` - show this help message and exit - -``--session-id SESSION_ID`` - ID of the session - -``--job-id JOB_ID`` - ID of the job - -``--job-tag JOB_TAG`` - Job tag value - -.. _freezer_session-update: - -freezer session-update ----------------------- - -.. code-block:: console - - usage: freezer session-update [-h] session_id file - -Update a session from a file - -**Positional arguments:** - -``session_id`` - ID of the session - -``file`` - Path to json file with the session - -**Optional arguments:** - -``-h, --help`` - show this help message and exit +.. toctree:: + details + freezer \ No newline at end of file diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..0421c3f --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,17 @@ +=================== + Contributor Guide +=================== + +Code is hosted at `git.openstack.org`__. Submit bugs to the python-freezerclient +project on `Launchpad`__. Submit code to the `openstack/python-freezerclient` +project using `Gerrit`__. + +__ https://git.openstack.org/cgit/openstack/python-freezerclient +__ https://storyboard.openstack.org/#!/project/openstack/freezer-api +__ https://docs.openstack.org/infra/manual/developers.html#development-workflow + + +.. toctree:: + :maxdepth: 2 + + testing diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst new file mode 100644 index 0000000..df4e47e --- /dev/null +++ b/doc/source/contributor/testing.rst @@ -0,0 +1,30 @@ +Testing + +The preferred way to run the unit tests is using ``tox``. There are multiple +test targets that can be run to validate the code. + +``tox -e pep8`` + Style guidelines enforcement. + +``tox -e py27`` + Traditional unit testing (Python 2.7). + +``tox -e py35`` + Traditional unit testing (Python 3.5). + +``tox -e cover`` + Generate a coverage report on unit testing. + +Functional testing assumes the existence of a `clouds.yaml` file as supported +by `os-client-config `__ +It assumes the existence of a cloud named `devstack` that behaves like a normal +DevStack installation with a demo and an admin user/tenant - or clouds named +`functional_admin` and `functional_nonadmin`. + +Refer to `Consistent Testing Interface`__ for more details. + +__ https://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst + +Refer to `Tester Use`__ for more details. + +__ https://wiki.openstack.org/wiki/Testr diff --git a/doc/source/index.rst b/doc/source/index.rst index b570f33..1512fa8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,7 +8,10 @@ Contents .. toctree:: :maxdepth: 2 + user/index + reference/index cli/index + contributor/index Indices and tables diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000..9fba461 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,41 @@ +The :mod:`freezerclient` Python API + +.. module:: freezerclient + :synopsis: A client for the OpenStack Freezer API. + +.. currentmodule:: freezerclient + +Basic Usage +----------- + +First create a client instance using a keystoneauth Session. For more +information on this keystoneauth API, see `Using Sessions`_. + +.. _Using Sessions: https://docs.openstack.org/keystoneauth/latest/using-sessions.html + +.. code-block:: python + + >>> from keystoneauth1 import identity + >>> from keystoneauth1 import session + >>> from freezerclient import client + >>> username='username' + >>> password='password' + >>> project_name='demo' + >>> project_domain_id='default' + >>> user_domain_id='default' + >>> auth_url='http://auth.example.com:5000/v3' + >>> auth = identity.Password(auth_url=auth_url, + ... username=username, + ... password=password, + ... project_name=project_name, + ... project_domain_id=project_domain_id, + ... user_domain_id=user_domain_id) + >>> sess = session.Session(auth=auth) + >>> freezer = client.Client(version='2',session=sess) + +It is also possible to use an instance as a context manager in which case +there will be a session kept alive for the duration of the with statement:: + + >>> from freezerclient import client + >>> freezer = client.Client('2') + >>> freezer.jobs.list_all() diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000..47d8662 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,6 @@ +User Guide + +.. toctree:: + :maxdepth: 2 + + shell diff --git a/doc/source/user/shell.rst b/doc/source/user/shell.rst new file mode 100644 index 0000000..5163e64 --- /dev/null +++ b/doc/source/user/shell.rst @@ -0,0 +1,86 @@ +The :program:`freezer` Shell Utility + +.. program:: freezer +.. highlight:: bash + +The :program:`freezer` shell utility interacts with OpenStack Freezer API from the +command line. It supports the entirety of the OpenStack Freezer API. + +You'll need to provide :program:`freezer` with your OpenStack Keystone user +information. You can do this with the `--os-username`, `--os-password`, +`--os-project-name` (`--os-project-id`), `--os-project-domain-name` +(`--os-project-domain-id`) and `--os-user-domain-name` (`--os-user-domain-id`) +options, but it's easier to just set them as environment variables by setting +some environment variables: + +.. envvar:: OS_USERNAME + + Your OpenStack Keystone user name. + +.. envvar:: OS_PASSWORD + + Your password. + +.. envvar:: OS_PROJECT_NAME + + The name of project for work. + +.. envvar:: OS_PROJECT_ID + + The ID of project for work. + +.. envvar:: OS_PROJECT_DOMAIN_NAME + + The name of domain containing the project. + +.. envvar:: OS_PROJECT_DOMAIN_ID + + The ID of domain containing the project. + +.. envvar:: OS_USER_DOMAIN_NAME + + The user's domain name. + +.. envvar:: OS_USER_DOMAIN_ID + + The user's domain ID. + +.. envvar:: OS_AUTH_URL + + The OpenStack Keystone endpoint URL. + +.. envvar:: OS_BACKUP_API_VERSION + + The OpenStack freezer API version. + +.. envvar:: OS_REGION_NAME + + The Keystone region name. Defaults to the first region if multiple regions + are available. + +For example, in Bash you'd use:: + + export OS_USERNAME=yourname + export OS_PASSWORD=yadayadayada + export OS_PROJECT_NAME=myproject + export OS_PROJECT_DOMAIN_NAME=default + export OS_USER_DOMAIN_NAME=default + export OS_AUTH_URL=http:///identity + export OS_BACKUP_API_VERSION=2 + +From there, all shell commands take the form:: + + freezer [arguments...] + +Run :program:`freezer help` to get a full list of all possible commands, and run +:program:`freezer help ` to get detailed help for that command. + +Reference +--------- + +For more information, see the reference: + +.. toctree:: + :maxdepth: 2 + + /cli/freezer