diff --git a/docs/manual/_ext/rbwebsite_refs.py b/docs/manual/_ext/rbwebsite_refs.py new file mode 100644 index 0000000000000000000000000000000000000000..ac6d4c9824f38ccf67193b5a4eebdbc7d0c2ec1e --- /dev/null +++ b/docs/manual/_ext/rbwebsite_refs.py @@ -0,0 +1,14 @@ +"""Sphinx extension for the Review Board documentation. + +This provides general cross-reference roles/directives to help link related +content in the documentation. + +Version Added: + 5.0.5 +""" + + +def setup(app): + app.add_crossref_type(directivename='rb-management-command', + rolename='rb-management-command', + indextemplate=('pair: %s; management command')) diff --git a/docs/manual/admin/extensions/index.rst b/docs/manual/admin/extensions/index.rst index 2bc8426e4d96486a4278db479d90f89df3f44bbb..85d49a2b8c2981dd8a46deecf582c66568192175 100644 --- a/docs/manual/admin/extensions/index.rst +++ b/docs/manual/admin/extensions/index.rst @@ -24,6 +24,8 @@ Please prefer to the particular extension's documentation for installation instructions. +.. _admin-ui-manage-extensions: + Managing Extensions =================== diff --git a/docs/manual/admin/sites/management-commands.rst b/docs/manual/admin/sites/management-commands.rst index 8214b9b6c08220a73d43cff95c1390b400ac65c1..be20352cc2d51b99f5555796b49595f8e79bf64a 100644 --- a/docs/manual/admin/sites/management-commands.rst +++ b/docs/manual/admin/sites/management-commands.rst @@ -1,3 +1,5 @@ +:tocdepth: 3 + .. _management-commands: ============================ @@ -5,126 +7,270 @@ Advanced Management Commands ============================ :command:`rb-site` provides a ``manage`` command for certain management tasks. -The format for the commands is always:: +The format for the commands is always: + +.. code-block:: console - $ rb-site manage /path/to/site command-name -- parameters + $ rb-site manage /path/to/sitedir command-name parameters The management commands that administrators are most likely to use are explained in detail in the following sections. -To get a complete list of all management commands, run:: +To get a complete list of all management commands, run: - $ rb-site manage /path/to/site help +.. code-block:: console -And to retrieve information on a specific management command:: + $ rb-site manage /path/to/sitedir help - $ rb-site manage /path/to/site help command-name +And to retrieve information on a specific management command: +.. code-block:: console -.. _search-indexing-management-command: + $ rb-site manage /path/to/sitedir help command-name -Search Indexing ---------------- -Review Board installations with indexed search enabled must periodically -index the database. This is done through the ``rebuild_index`` and -``update_index`` management commands (The ``index`` command will be -deprecated in a future release). +.. _management-commands-configuration: -To perform a full index:: +Configuration Commands +====================== - $ rb-site manage /path/to/site rebuild_index +These commands are used to inspect or update your Review Board configuration -To perform an index update:: +* :rb-management-command:`get-siteconfig`: Retrieve a value from configuration +* :rb-management-command:`set-siteconfig`: Set a configuration value +* :rb-management-command:`list-siteconfig`: List the current configuration +* :rb-management-command:`resolve-check`: Resolve a required system check for + an upgrade - $ rb-site manage /path/to/site update_index -- -a -where ```` is the number of hours since the last update. We recommend -using ``-a 1`` and run the update command every 10 minutes. This command should -be run periodically in a task scheduler, such as :command:`cron` on Linux. +.. rb-management-command:: get-siteconfig +.. program:: get-siteconfig -A sample ``crontab`` entry is available at :file:`conf/cron.conf` under -an installed site directory. +``get-siteconfig`` - Get a Configuration Value +---------------------------------------------- -The generated search index will be placed in the -:ref:`search index directory ` specified in the -:ref:`general-settings` page. By default, this should be the -:file:`search-index` directory in your site directory. +This command displays the value for a Review Board configuration setting. It +can be useful for automation scripts. -.. _creating-a-super-user: +Usage +~~~~~ -Creating a Super User ---------------------- +.. code-block:: console -It is possible to create a new super user account without using the -website. This can be important if the main super user account is for -whatever reason disabled or if the login information is lost. + $ rb-site manage /path/to/sitedir get-siteconfig --key -To create a new super user account, run:: +The value will be outputted directly. - $ rb-site manage /path/to/site createsuperuser +Options +~~~~~~~ -This will prompt for the username and password of the account. You must -specify a user that doesn't already exist in the database. Once this is -finished, you should be able to log in under the new account and fix any -problems you have. +.. option:: --key KEY + The name of the configuration key to fetch. -Opening a Command Shell ------------------------ -Power users who wish to run Python commands against an installed Review -Board server can do so with the ``shell`` management command. This can be -useful if you're a developer looking to test some code against Review -Board. +.. rb-management-command:: list-siteconfig +.. program:: list-siteconfig -To open a Python command shell, run:: +``list-siteconfig`` - List Configuration Settings +------------------------------------------------- - $ rb-site manage /path/to/site shell +This command lists all stored configuration settings as JSON data. This is +useful for inspecting the current settings and finding keys to change. -Resetting Review Request Counters ---------------------------------- +Usage +~~~~~ -The counters in the Dashboard along the left-hand side, indicating the -number of review requests, can potentially be incorrect if changes were -made manually to the database or if there was an error while attempting to -save information to the database. +.. code-block:: console -You can fix these counters by running:: + $ rb-site manage /path/to/sitedir list-siteconfig - $ rb-site manage /path/to/site fixreviewcounts -This is done automatically when upgrading a site. +.. rb-management-command:: resolve-check +.. program:: resolve-check +``resolve-check`` - Resolve System Check +---------------------------------------- -.. _management-command-invalidate-api-tokens: +This command is used to resolve certain system checks that can occur during +installation/upgrade. These are steps that are required by Review Board but +cannot be performed automatically. -Invalidating API Tokens ------------------------ +Review Board will tell you when you need to run this command, and what +parameters to provide. -.. versionadded:: 5.0 -The :ref:`API tokens ` for a set of users can be -invalidated by running:: +Usage +~~~~~ - $ rb-site manage /path/to/site invalidate-api-tokens ... +.. code-block:: console -To invalidate the tokens of all users, run:: + $ rb-site manage /path/to/sitedir resolve-check - $ rb-site manage /path/to/site invalidate-api-tokens --all +The status or error will be shown. -You can also supply a reason for invalidating the tokens by passing the -``--reason `` argument. +.. rb-management-command:: set-siteconfig +.. program:: set-siteconfig + +``set-siteconfig`` - Set a Configuration Value +---------------------------------------------- + +This command sets a new value for an existing configuration setting. It can be +useful for automation scripts. + +.. note:: + + Not all settings can be changed through this command. + + Some settings require using the :rb-management-command:`shell` command, + and should only be changed if directed by `Beanbag support`_. + + +.. _management-commands-data: + +Data Commands +============= + +These commands help with your site's data management. + +* :rb-management-command:`condensediffs`: + Upgrade diff storage and condense the diffs in the database. This can reduce + database size when upgrading Review Board. + +* :rb-management-command:`import-ssh-keys`: + Import the host's SSH keys into the database, for shared SSH storage. + This requires `Power Pack`_. + + +.. rb-management-command:: condensediffs +.. program:: condensediffs + +``condensediffs`` - Condense/Upgrade Diff Storage +------------------------------------------------- + +Review Board occasionally introduces new and improved ways of storing diffs, +offering new features or reducing storage requirements. This command is used +to move any older diffs into the latest type of diff storage. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir condensediffs [] + + +Options +~~~~~~~ + +.. option:: --max-diffs COUNT + + Specifies a maximum number of migrations to perform. This is useful if + you have a lot of diffs to migrate and want to do it over several + sessions. + +.. option:: --no-progress + + Don't show progress information or totals while migrating. You might want + to use this if your database is taking too long to generate total migration + counts. + +.. option:: --show-counts-only + + Show the number of diffs expected to be migrated, without performing a + migration. + + +.. rb-management-command:: import-ssh-keys +.. program:: import-ssh-keys + +``import-ssh-keys`` - Import SSH Keys +------------------------------------- + +This is used to import any existing SSH keys into Power Pack's distributed +SSH key storage, used by many types of repositories. + +Distributed SSH keys are shared across all Review Board servers in your +network serving the same site. It's useful for Docker environments and other +multi-server setups. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir import-ssh-keys + +This will automatically import the keys into storage and then exit. + +.. note:: + + `Power Pack`_ must be installed and licensed in order to run this command + or use distributed SSH keys. + + +.. _management-commands-debugging: + +Debugging Commands +================== + +These commands give you some insight into your Review Board installation, +helping you inspect information or perform certain commands. + +* :rb-management-command:`dbshell`: + Open a database shell using your standard database tools (e.g., + :command:`mysql` or :command:`psql`). + +* :rb-management-command:`find-large-diffs`: + Scan the database looking for very large diffs that may be contributing to + performance problems. + +* :rb-management-command:`shell`: + Open a Python shell in the Review Board environment. + + +.. rb-management-command:: dbshell +.. program:: dbshell + +``dbshell`` - Open a Database Shell +----------------------------------- + +This command opens a database shell using Review Board's credentials. This can +be useful for advanced debugging and database management. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir dbshell + +You can then issue SQL statements with the same permissions available to your +Review Board server. + +.. danger:: + This will have direct access to your database. If you're not careful, this + can lead to data loss or other problems. + + We recommend using this only if you're experienced and have a backup + of your database, or are guided by `Beanbag support`_. + + +.. rb-management-command:: find-large-diffs +.. program:: shell .. _management-command-find-large-diffs: -Find Large Diffs ----------------- +``find-large-diffs`` - Find Very Large Diffs +-------------------------------------------- .. program:: find-large-diffs @@ -209,4 +355,538 @@ The following options are available to customize your scan: Disable prompting for confirmation before performing the scan. +.. rb-management-command:: shell +.. program:: shell + +``shell`` - Open a Command Shell +-------------------------------- + +Power users who wish to run Python commands against an installed Review +Board server can do so with the ``shell`` management command. This can be +useful if you're a developer looking to test some code against Review +Board. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir shell + +You can then run Python code within the context of Review Board. + +.. danger:: + + This will have direct access to your database and Review Board system + files. If you're not careful, this can lead to data loss or other + problems. + + We recommend using this only if you're experienced and have a backup + of your database, or are guided by `Beanbag support`_. + + +.. _management-commands-extensions: + +Extension Commands +================== + +These commands let you manage your installed extensions without logging into +Review Board. These can be useful if you're encountering problems starting +up due to a problem with an extension. + +* :rb-management-command:`disable-extension`: + Disable an extension. + +* :rb-management-command:`enable-extension`: + Enable an extension. + +* :rb-management-command:`list-extensions`: + List all installed and available extensions. + + +.. rb-management-command:: disable-extension +.. program:: disable-extension + +``disable-extension`` - Disable Extension +----------------------------------------- + +This disables one or more extensions. It's the equivalent of going into +:guilabel:`Administration UI -> Extensions` and disabling extensions, and +can be useful for automation scripts. + +See :ref:`admin-ui-manage-extensions`. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir disable-extension EXTENSION_ID [...] + +One or more extension IDs can be provided. See +:rb-management-command:`list-extensions` to see the list of IDs. + + +.. rb-management-command:: enable-extension +.. program:: enable-extension + +``enable-extension`` - Enable Extension +--------------------------------------- + +This enables one or more extensions. It's the equivalent of going into +:guilabel:`Administration UI -> Extensions` and enabling extensions, and +can be useful for automation scripts. + +See :ref:`admin-ui-manage-extensions`. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir enable-extension EXTENSION_ID [...] + +One or more extension IDs can be provided. See +:rb-management-command:`list-extensions` to see the list of IDs. + + +.. rb-management-command:: list-extensions +.. program:: list-extensions + +``list-extensions`` - List Extensions +------------------------------------- + +Lists the extensions registered with Review Board. The name, enabled status, +and extension ID will be shown for each extension. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir list-extensions [] + + +Options +~~~~~~~ + +.. option:: --enabled + + Filter the list to enabled extensions only. + + +.. _management-commands-packages: + +Package Management/Runtime Commands +=================================== + +.. versionadded:: 5.0.5 + +These commands help you manage packages in your Review Board installation, +and work with the correct version of Python. They're recommended over using +the corresponding system-level commands. + +* :rb-management-command:`pip`: + Run the correct :command:`pip` package management tool for Review Board. + +* :rb-management-command:`python`: + Run the correct :command:`python` interpreter for Review Board. + + +.. rb-management-command:: pip +.. program:: pip + +``pip`` - Python Package Tool +----------------------------- + +.. versionadded:: 5.0.5 + +This wraps around the correct version of :command:`pip` for your Review Board +environment. It's used for installing or managing packages for Review Board. + +See the `pip documentation`_ for usage instructions. + + +.. _pip documentation: https://pip.pypa.io/ + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir pip [] + +To install a package: + +.. code-block:: console + + $ rb-site manage /path/to/sitedir pip install + +To upgrade a package: + +.. code-block:: console + + $ rb-site manage /path/to/sitedir pip install -U + +To uninstall a package: + +.. code-block:: console + + $ rb-site manage /path/to/sitedir pip uninstall + +To show information on a package: + +.. code-block:: console + + $ rb-site manage /path/to/sitedir pip show + +To list installed packages: + +.. code-block:: console + + $ rb-site manage /path/to/sitedir pip list + + +.. rb-management-command:: python +.. program:: python + +``python`` - Python Interperter +------------------------------- + +.. versionadded:: 5.0.5 + +This wraps around the correct version of :command:`python` for your Review +Board environment. It's used for executing Python code in your Review Board +environment. + +This differs from :rb-management-command:`shell` in that Python code *will +not* run within the Review Board process. + +.. _pip documentation: https://pip.pypa.io/ + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir python [] + + +.. _management-commands-search: +.. _search-indexing-management-command: + +Search Commands +=============== + +Review Board installations with indexed search enabled must periodically +index the database. This is done through the following commands: + +* :rb-management-command:`clear_index`: + Clear the search index. + +* :rb-management-command:`rebuild_index`: + Rebuild the search index from scratch. + +* :rb-management-command:`update_index`: + Create or update the configured search index. + +A sample ``crontab`` file is available at :file:`conf/cron.conf` under +an installed site directory. + +The generated search index will be placed in the +:ref:`search index directory ` specified in the +:ref:`general-settings` page. By default, this should be the +:file:`search-index` directory in your site directory. + +.. note:: + + If you have :ref:`on-the-fly indexing ` enabled, + the search index should stay up-to-date automatically without running + :rb-management-command:`update_index`. + + +.. rb-management-command:: clear_index +.. program:: clear_index + +``clear_index`` - Clear the Search Index +---------------------------------------- + +This command will erase the current search index. A rebuild will be required +before any new searches can be conducted. + +By default, this will prompt for confirmation before clearing the index. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir clear_index []n + + +Options +~~~~~~~ + +.. option:: --noinput + + The search index will be cleared without prompting for confirmation. + + +.. rb-management-command:: rebuild_index +.. program:: rebuild_index + +``rebuild_index`` - Rebuild the Search Index +-------------------------------------------- + +This command will erase the current search index and then rebuild it from +scratch. This can take some time. + +By default, this will prompt for confirmation before clearing the index. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir rebuild_index [] + + +Options +~~~~~~~ + +.. option:: --noinput + + The rebuild will happen without prompting for confirmation. + +.. option:: -b BATCH_SIZE, --batch-size BATCH_SIZE + + The number of items to index per batch. + + This is an advanced option. The default is usually safe. + +.. option:: -k NUM_WORKERS, --workers NUM_WORKERS + + The number of worker processes to run to perform the indexing. This can + reduce the time needed to index the database. + +.. option:: -t MAX_RETRIES, --max-retries MAX_RETRIES + + The number of times to retry a write to the search index if an error + (such as a communication error) occurs. + + +.. rb-management-command:: update_index +.. program:: update_index + +``update_index`` - Update the Search Index +------------------------------------------ + +The :command:`update_index` management command will create or update the +current search index with any new content. It can be run periodically. + +By default, this will prompt for confirmation before clearing the index. + +If :ref:`on-the-fly indexing ` is enabled, this +command is not required, but can help with catching objects that may have +failed to write due to temporary failures in the search backend. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir update_index -r -a [] + +```` is the number of hours back to look for new items to include in +the search index. + +This command should be run periodically in a task scheduler, such as +:command:`cron` on Linux. + +We recommend using ``-a 1`` and scheduling the command to run every 10 +minutes. This helps keep your index up-to-date while also allowing for some +buffer room in case of a temporary outage or upgrade. + +All other options should be considered optional. + + +Options +~~~~~~~ + +.. option:: --noinput + + The rebuild will happen without prompting for confirmation. + +.. option:: -a HOURS, --age HOURS + + The number of hours back to consider an item new. We recommend ``1``. + +.. option:: -m MINUTES, --minutes MINUTES + + The number of minutes back to consider an item new. + +.. option:: -s START_DATE, --start START_DATE + + The starting date range for any objects considered for indexing. This + must be in :term:`ISO8601 format`. + +.. option:: -e END_DATE, --end END_DATE + + The ending date range for any objects considered for indexing. This + must be in :term:`ISO8601 format`. + +.. option:: -r, --remove + + Remove objects from the index that are no longer present in the database. + +.. option:: -b BATCH_SIZE, --batch-size BATCH_SIZE + + The number of items to index per batch. + + This is an advanced option. The default is usually safe. + +.. option:: -k NUM_WORKERS, --workers NUM_WORKERS + + The number of worker processes to run to perform the indexing. This can + reduce the time needed to index the database. + +.. option:: -t MAX_RETRIES, --max-retries MAX_RETRIES + + The number of times to retry a write to the search index if an error + (such as a communication error) occurs. + + +.. _management-commands-users: + +User Management Commands +======================== + +These commands can help with managing users and API tokens on your server: + +* :rb-management-command:`changepassword`: + Change the password for a user. + +* :rb-management-command:`createsuperuser`: + Create a new Review Board administrator. + +* :rb-management-command:`invalidate-api-tokens`: + Invalidate API tokens for one or more users. + + +.. rb-management-command:: changepassword +.. program:: changepassword + +``changepassword`` - Change a User's Password +--------------------------------------------- + +This command will change an existing user's password to a newly-supplied one, +helping them get back into the system if they're unable to reset their own +password. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir changepassword + +This will prompt for a new password for the user. + + +.. rb-management-command:: createsuperuser +.. program:: createsuperuser +.. _creating-a-super-user: + +``createsuperuser`` - Create a Super User +----------------------------------------- + +It is possible to create a new super user account without using the +website. This can be important if the main super user account is for +whatever reason disabled or if the login information is lost. + + +Usage +~~~~~ + +.. code-block:: console + + $ rb-site manage /path/to/sitedir createsuperuser + +This will prompt for the username and password of the account. You must +specify a user that doesn't already exist in the database. Once this is +finished, you should be able to log in under the new account and fix any +problems you have. + + +Options +~~~~~~~ + +.. option:: --email + + The optional e-mail address for the new user. If specified, you won't be + prompted for one. + +.. option:: --username + + The optional username for the new user. If specified, you won't be + prompted for one. + + +.. rb-management-command:: invalidate-api-tokens +.. program:: invalidate-api-tokens +.. _management-command-invalidate-api-tokens: + +``invalidate-api-tokens`` - Invalidate API Tokens +------------------------------------------------- + +.. versionadded:: 5.0 + +In the event of security issues, you can invalidate :ref:`API tokens +` for specific users or all users on your server. + + +Usage +~~~~~ + +To invalidate for specific users: + +.. code-block:: console + + $ rb-site manage /path/to/sitedir invalidate-api-tokens ... + +To invalidate the tokens of all users, run: + +.. code-block:: console + + $ rb-site manage /path/to/sitedir invalidate-api-tokens --all + +You can also supply a reason for invalidating the tokens by passing the +``--reason `` argument. + + +Options +~~~~~~~ + +.. option:: -a, --all + + Invalidate all tokens on the server. + +.. option:: -r REASON, --reason REASON + + Store a reason the token was invalidated. This will show up on the token + information. + + +.. _Beanbag support: https://www.reviewboard.org/support/ .. _contacting support: https://www.reviewboard.org/support/ +.. _Power Pack: https://www.reviewboard.org/powerpack/ diff --git a/docs/manual/conf.py b/docs/manual/conf.py index 6e93a600022974c98ae4a997073d062a58be52d6..01955aa1535115d1c6dd5bc88f3a4061882bbdc7 100644 --- a/docs/manual/conf.py +++ b/docs/manual/conf.py @@ -76,6 +76,7 @@ extensions = [ 'beanbag_docutils.sphinx.ext.metadata', 'beanbag_docutils.sphinx.ext.ref_utils', 'webapidocs', + 'rbwebsite_refs', ] # Add any paths that contain templates here, relative to this directory. diff --git a/reviewboard/cmdline/rbsite.py b/reviewboard/cmdline/rbsite.py index 4a07a599eab3036ab11218ec8bdb22bd2861ad75..92bf17e5f9652b591fa4e6324d83910ce812c55a 100755 --- a/reviewboard/cmdline/rbsite.py +++ b/reviewboard/cmdline/rbsite.py @@ -2928,6 +2928,10 @@ class ManageCommand(Command): 'Open a database shell using your standard database ' 'tools (e.g., mysql or psql).' ), + 'find-large-diffs': ( + 'Scan the database looking for very large diffs that may ' + 'be contributing to performance problems.' + ), 'shell': ( 'Open a Python shell in the Review Board environment.' ), @@ -2955,6 +2959,9 @@ class ManageCommand(Command): 'Users': { 'changepassword': 'Change the password for a user.', 'createsuperuser': 'Create a new Review Board administrator.', + 'invalidate-api-tokens': ( + 'Invalidate API tokens for one or more users.' + ), }, }