Rok v0.9

Rok Composer

Introduction

Rok v0.9 introduces node-local fisks, that reside on only one node. The v3 map version has been created in Rok Composition Service to support node-local fisks. Map version v3 is now the default version, so during the upgrade process you must pin new composers to v2 before upgrading all nodes.

Upgrade steps

For each node perform the following steps:

  1. Stop the Rok Composition Services, i.e., rok-composerd and rok-hasherd.
  2. Upgrade Rok to v0.9.
  3. Add the –map-version 2 option to the Composer daemon (e.g. map-version=2 in [composerd.0] section of /etc/rok/daemons.conf).
  4. Start the Rok Composition Services.

After upgrading all nodes to v0.9, remove the –map-version 2 CLI option and restart all composers.

Finally, on one node run the following command to upgrade all existing maps:

$ rok-composer-tool map-upgrade --all

This command will upgrade all maps to v3 after creating a backup of the previous version. After verifying that everything works correctly, you can delete the backups by running rok-gc with the –delete-backups CLI option:

$ rok-gc --delete-backups

Rok Gateway

Before restarting the Rok Gateway gunicorn process and daemons, make sure to update the following options in the Gateway’s configuration files. More information about these options can be found in the Gateway’s configuration examples.

  • In /etc/rok/gw/api/10-services.conf.py, set the ROK_UI_BASE_URL and ROK_API_BASE_URL settings to the base URLs that the Rok UI and API can be accessed from.
  • In /etc/rok/gw/api/10-auth.conf.py, the STATIC_AUTH_TOKENS setting was renamed to STATIC_AUTH_USERS, and allows defining additional information about the users of the Gateway when using static authentication. Additionally, starting from this version, the Gateway does not automatically login any of its users when using static authentication. In order retain the old auto-login behavior, the STATIC_AUTH_AUTOLOGIN_USER setting must be set to the ID of the user as which clients will automatically login.

Gunicorn

The /etc/rok/gunicorn-hooks/gunicorn-stderr-logging.py hook was renamed to /etc/rok/gunicorn-hooks/gunicorn-hooks.py. Change all gunicorn configuration files under /etc/gunicorn.d/ that reference this hook.

Indexer

The ROK_FORT_URL setting in /etc/rok/indexer/indexer.conf.py has been split to the ROK_FORT_INTERNAL_URL and ROK_FORT_PUBLIC_URL. The first one is the URL that Indexer is using to communicate with Fort (e.g. the address that Fort gunicorn is listening) while the second one it the URL that Indexer advertises to clients to communicate with Fort (e.g. the address that Fort nginx is listening).

Fort

Apply any database migrations introduced in v0.9 with:

$ rok-fort-manage migrate

Rok Gateway/Fort/Indexer

Rok Gateway, Fort and Indexer are Django projects, which up until v0.8 shipped with a dummy Django SECRET_KEY. While this SECRET_KEY should never be used in production, this was never enforced and it’s possible that an installation may have used it unknowingly.

Starting from v0.9, all dummy SECRET_KEYs are removed, so all new installations are required to define their own, if they haven’t already done so.

For existing installations that happen to use the dummy key, the administrators are advised to do the following:

  • In the Rok Gateway and Indexer services, the SECRET_KEY is not currently used, so the administrators are advised to change it immediately.
  • In Fort, the SECRET_KEY is currently used for the following purposes:
    1. For encrypting the bcrypt hashes of the user passwords.
    2. For hashing the tokens.

Therefore, for Fort specifically, the SECRET_KEY must change and the following steps must take place, in order to re-encrypt the users’ passwords with the new SECRET_KEY:

  1. Before upgrading the Rok Fort service: Run the following command in the node where Fort is installed, to retrieve the old SECRET_KEY. Store it temporarily somewhere safe:

    $ rok-fort-manage diffsettings 2>&1 | grep SECRET_KEY
    
  2. Upgrade the Rok Fort service.

  3. Stop the Rok Fort service, so that new accounts are not created.

  4. Get a backup of the Fort database, since the following commands will alter it.

  5. Run the following management command to check if the user passwords can be re-encrypted:

    $ DJANGO_SECRET_KEY=${OLD_SECRET_KEY} rok-fort-manage password-reencrypt --dry-run
    

    Note

    This command runs in --dry-run mode so that no changes are committed to the database. Also, this command accepts the old SECRET_KEY that was retrieved in step 1, as an environment variable.

  6. If the command returns successfully, run it again without --dry-run:

    $ DJANGO_SECRET_KEY=${OLD_SECRET_KEY} rok-fort-manage password-reencrypt
    
  7. Destroy the old SECRET_KEY and restart the Rok Fort service.

Note that after the above steps take place, the users of the Indexer and Gateway services will need to login again, since their old tokens will be invalid.

Rok appliances

Security issues

Rok appliances until v0.9 upon initial configuration created world readable private SSL keys, with wrong group owner. This not only is a security issue, but also prevents some programs from using those keys (e.g., postgresql).

Furthermore, the /etc/ssl/private directory (where private keys reside) was not marked as appliance configuration, resulting in mismatch between SSL certificates and SSL keys on appliance upgrade.

Administrators should make sure to fix the above issues manually before upgrading any appliance. To do so, on every existing Rok appliance, using the following commands:

# chmod 0640 /etc/ssl/private/*
# chown root:ssl-cert /etc/ssl/private/*
# rok-config-add /etc/ssl/private
# rok-config-save