..
  Please note: if you change this file you need to rebuild the manpage using the
  following command and commit the manpage file too:

  sphinx-build -b man docs/source/ docs/man/
  git add docs/man/sfmanager.1
  git commit

.. toctree::

CLI for Software Factory
========================

This documentation describes the shell utility **sfmanager**, which is a CLI for
the managesf REST API interface in Software Factory.

Introduction
------------

Global options
^^^^^^^^^^^^^^

By default all actions require authentication as well as some information about
the remote servers.

\--url <http://sfgateway.dom>
    URL of the managesf instance

Optional:

\--insecure
    Disable SSL certificate verification.

\--debug
    Enable debug messages in console. Disabled by default

\--json
    Output command results as JSON, if applicable

Authentication (cauth)
^^^^^^^^^^^^^^^^^^^^^^

\--auth user:password
    Username and password to use when accessing the managesf interface.
    This option is only valid if it is a local user within Software Factory

\--api-key abcde1234
    User API key that can be found on the user's settings page

\--cookie uid=...
    The HTTP auth cookie, can be found with the developer console in any
    web browser

\--github-token kkkk
    A Github API token, if the user is authenticating to Software Factory with
    his/her Github account

Authentication (keycloak)
^^^^^^^^^^^^^^^^^^^^^^

\--auth user:password
    Username and password to use when accessing the managesf interface.
    This option is only valid if the user has defined a password on keycloak.

\--token xxx
    A JWT bearer token generated by keycloak.


RC file
^^^^^^^

Rather than writing these global options each time the CLI is used, they can
be stored in $HOME/.software-factory.rc:

.. code-block:: yaml

 sf_environment:
    url: https://sftests.com
    insecure: true
    # use one of these auth methods at most. They are listed in priority order
    # in case several are present.
    auth:
      username: admin
      # password can be omitted if username is provided; it will have to be
      # manually set within the CLI
      password: userpass
      api-key: edcba
      cookie: nomnom
      github-token: abcde
      jwt: xxxx
    debug: false

If you are using distinct instances of Software Factory, more environments can
be defined in the rc file in the same fashion.

To apply an environment configuration, use:

.. code-block:: bash

 sfmanager -e sf_environment ...

User management
---------------

.. _user-management:

These commands manage the local users, that are not using external
authentication systems like Github.


Add user
^^^^^^^^

Creates a new user in the internal backend and registers the user in every authenticated service

\--username [username], -u [username]
    A unique username/login

\--password [password], -p [password]
    The user password, can be provided interactively if this option is empty

\--email [email], -e [email]
    The user email

\--fullname [John Doe], -f [John Doe]
    The user's full name, defaults to username

\--ssh-key [/path/to/pub_key], -s [/path/to/pub_key]
    The user's ssh public key file

.. code-block:: bash

 sfmanager -e my_sf user create --username jdoe --password secret --fullname "User Tester" \
                --email jane@doe.org

Update user
^^^^^^^^^^^

Update an existing local user. A user can update it's own details, and admins
can also update other user details. Takes the same arguments as user create.
The options `--fullname` and `--ssh-key` (if updated) won't be taken in account
inside SF services. Only the password can be updated.

.. code-block:: bash

 sfmanager -e my_sf user update --username jdoe --password unguessable


Delete user
^^^^^^^^^^^

Disable the user's account. That does not prevent the user from contributing, it
only prevents the user from login in to Software Factory.

.. code-block:: bash

 sfmanager -e my_sf user delete --username jdoe


Registered User management
--------------------------

These commands manage the global users. Please note that these commands do not
modify users on Software Factory's local authentication backend.


Register user
^^^^^^^^^^^^^

Registers the user with all the services. The typical use
case is to provision a user before his or her first login on Software Factory,
so that project memberships can be set ahead of time.

\--username [username], -u [username]
    A unique username/login

\--email [email], -e [email]
    The user email

\--fullname [John Doe], -f [John Doe]
    The user's full name, defaults to username

.. code-block:: bash

 sfmanager -e my_sf sf_user create --username jdoe --fullname "User Tester" \
                --email jane@doe.org


Deregister user
^^^^^^^^^^^^^^^

This command removes the user from all the services. It does not delete a user
from the local authentication backend; the user can also register again simply
by logging into Software Factory. The typical use case is when a user experiences
a problem with external authentication, removing the user from the services and
relogging might be a solution.

.. code-block:: bash

 sfmanager -e my_sf sf_user delete --username jdoe

or

.. code-block:: bash

 sfmanager -e my_sf sf_user delete --email jdoe@users.com

List registered users
^^^^^^^^^^^^^^^^^^^^^

This command lists all the users currently registered (ie who have logged in at
least once) on Software Factory.

For each user, the following information is returned:

* the username
* the user's full name
* the user's email
* the user's internal id within manageSF
* the user's id within cauth, the SSO system

.. code-block:: bash

 sfmanager -e my_sf sf_user list

.. _managesf_backup:

Backups
-------

Backups include database dumps from Gerrit, Jenkins, MariaDB, cauth and managesf
as well as some important configuration files like Gerrit replication settings,
SSH keys and deployment settings. This includes credentials; please see below how to
store encrypted backups.

Create a new backup
^^^^^^^^^^^^^^^^^^^

SF exposes ways to perform and retrieve a backup of all the user data store in
your SF installation. This backup can be used in case of disaster to quickly
recover user data on the same or another SF installation (of the same version).

By default only the administrator can manage backups. This can be changed by
editing the rules "managesf.backup:create" and "managesf.backup:get" in the policy
file in Software Factory's **config** repository.

To start the backup:

.. code-block:: bash

 sfmanager -e my_sf system backup_start

Once the server generated the tar file of the backup you can then download it with
the following command:

.. code-block:: bash

 sfmanager -e my_sf system backup_get

A file called "sf_backup.tar.gz" will be created in the local directory.


Using GPG to encrypt and decrypt backups
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is recommended to store the backup files encrypted when using external
storage services, since the user and administrative credentials are included
in the backup.

When using the export_backup_swift.sh shell script included in SF, all backups
are automatically encrypted using GPG before being uploaded to Swift. A special
public GPG key is required for this, and it has to be stored on the SF node.
To create this key, do the following:

.. code-block:: bash

 gpg --gen-key  # Use "sfadmin" as name when creating the key
 gpg --export -a sfadmin > sfadmin.pub
 gpg --export-secret-key -a sfadmin > sfadmin.key

Make sure you keep the sfadmin.key in a safe place.

You have to copy this public key to the SF node, and import it as root user.

.. code-block:: bash

 scp sfadmin.pub root@sftests.com:.
 gpg --import sfadmin.pub

If you need to restore from a backup, you need to decrypt the tar.gz file first.

.. code-block:: bash

 gpg -o sf_backup.tar.gz -d sf_backup.tar.gz.gpg


Request a password to access the Gerrit API
-------------------------------------------

To request a random password to access the Gerrit API for the current user. This
is useful for using tools like  `gertty <https://github.com/stackforge/gertty>`_ .

.. code-block:: bash

 sfmanager -e my_sf gerrit_api_htpasswd generate_password

and to deactivate the password from Gerrit.

.. code-block:: bash

 sfmanager -e my_sf gerrit_api_htpasswd delete_password

Nodepool images management
--------------------------

Sfmanager can be used to trigger manual updates on nodepool images, whether they
are based on cloud images or on images built with Disk-Image-Builder (DIB).

List images
^^^^^^^^^^^

.. code-block:: bash

 sfmanager -e my_sf image list [-i image_name] [-p provider_name]

List images (DIB)
^^^^^^^^^^^^^^^^^

.. code-block:: bash

 sfmanager -e my_sf dib-image list [-i image_name]

Update images
^^^^^^^^^^^^^

.. code-block:: bash

 sfmanager -e my_sf image update -i cloud_image_name -p provider_name

Update images (DIB)
^^^^^^^^^^^^^^^^^^^

First, rebuild the DIB image locally:

.. code-block:: bash

 sfmanager -e my_sf dib-image update -i dib_image_name

Then recreate a cloud image on a provider:

.. code-block:: bash

 sfmanager -e my_sf dib-image upload -i cloud_image_name -p provider_name

Get build logs (DIB)
^^^^^^^^^^^^^^^^^^^^

This command will download build logs for a given DIB image:

.. code-block:: bash

 sfmanager -e my_sf dib-image logs -i dib_image_name

Nodes management
----------------

Sfmanager can be used to deal with existing executor nodes.

List nodes
^^^^^^^^^^

The following command will list the current nodes spawned by nodepool:

.. code-block:: bash

 sfmanager -e my_sf node list

This will list among other things current nodes' ids, ip addresses, and statuses.

Hold a node
^^^^^^^^^^^

A node can be held so that nodepool will not destroy it once the job it was
spawned for has completed with the following command:

.. code-block:: bash

 sfmanager -e my_sf node hold -i node_id

Inject an SSH key on a node
^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is possible to inject an SSH key on a running node to allow someone to log
into it remotely, with the following command:

.. code-block:: bash

 sfmanager -e my_sf node add-user-key -k /path/to/public_key -i node_id

Delete a node
^^^^^^^^^^^^^

A node can be scheduled for immediate deletion with the following command:

.. code-block:: bash

 sfmanager -e my_sf node delete -i node_id

Jobs management
---------------

Sfmanager can be used to manage the execution of jobs.

List jobs
^^^^^^^^^

You can list jobs for a specific job name (for example *config-update*) with the
following command:

.. code-block:: bash

 sfmanager -e my_sf job list -j job-name

the following optional arguments can be used for filtering:

\--c review-change
    list jobs that were triggered for this specific review number

if --c is used, it can be further filtered with

\--p patchset
    to list jobs that were triggered for a specific patchset of that review


Fetch a job's parameters
^^^^^^^^^^^^^^^^^^^^^^^^

You can list the parameters that were used to trigger a specific job:

.. code-block:: bash

 sfmanager -e my_sf job parameters -j job-name -i job-id

Fetch a job's logs
^^^^^^^^^^^^^^^^^^

You can get the URL where the logs of a specific job are stored:

.. code-block:: bash

 sfmanager -e my_sf job logs -j job-name -i job-id

The following optional argument can be used:

\--fetch
    downloads and outputs the actual complete logs

Run a job
^^^^^^^^^

You can trigger a job manually:

.. code-block:: bash

 sfmanager -e my_sf job run -j job-name

Optional parameters:

\--parameters '{"param1": "value1", "param2": "value2" ...}'
    a list of parameters to use to run the job. The parameters must be passed
    as a JSON dictionary in the form {"parameter name": "parameter value"}

\--clone-from job-id
    the job will reuse parameters from job-id. If --parameters is used at the
    same time, the new parameters take precedence.

Stop a job
^^^^^^^^^^

you can cancel a running job:

.. code-block:: bash

 sfmanager -e my_sf job stop -j job-name -i job-id

Project
-------

sfmanager can be used to clone repositories part of a project.

Clone project's repositories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

 sfmanager --url <https://sfgateway.dom> project clone -p internal -d ~/git/internal
