Rok 0.9

Rok Composer

Introduction

Rok v0.9 introduces node-local fisks, that reside on only one node. We created the v3 map version 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, update the following options in the Gateway's configuration files. You can find more information about these options 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 from which you can access the Rok UI and API.
  • In /etc/rok/gw/api/10-auth.conf.py, we renamed STATIC_AUTH_TOKENS setting to STATIC_AUTH_USERS, and it 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, set the STATIC_AUTH_AUTOLOGIN_USER setting to the ID of the user as which clients will automatically login.

Gunicorn

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

Indexer

We split the ROK_FORT_URL setting in /etc/rok/indexer/indexer.conf.py to 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, we removed all dummy SECRET_KEYs, 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, we advise the administrators to do the following:

  • In the Rok Gateway and Indexer services, the SECRET_KEY is not currently used, so the we advise the administrators 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, you must change the SECRET_KEY and follow the next steps, 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 it doesn't create new accounts.

  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.

As an administrator, you should make sure to fix the above issues manually before upgrading any appliance. To do so, use the following commands on every existing Rok appliance:

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