SFMANAGER(1)

NAME
sfmanager - sfmanager Documentation

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 xxxx
    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:

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
   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:

sfmanager -e sf_environment ...

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

    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.

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.

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

    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.

sfmanager -e my_sf sf_user delete --username jdoe

or

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

    sfmanager -e my_sf sf_user list

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:

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:

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:

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.

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.

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 .

sfmanager -e my_sf gerrit_api_htpasswd generate_password

and to deactivate the password from Gerrit.

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

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

  List images (DIB)

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

  Update images

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

  Update images (DIB)

First, rebuild the DIB image locally:

sfmanager -e my_sf dib-image update -i dib_image_name

Then recreate a cloud image on a provider:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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

AUTHOR
Red Hat

COPYRIGHT
2015, 2016 Red Hat