Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


Skip to end of metadata
Go to start of metadata

This article describes how to upgrade Smart ID Digital Access component (Hybrid Access Gateway), either from Digital Access Admin or from the console. 

Also offline Docker upgrade is described.

Expand/Collapse All

Prerequisites

 Prerequisites

Before upgrading Digital Access component, make sure that the following things apply:

  • The Digital Access component Appliance must be able to access following url to fetch a new upgrade:
  • There is a service window planned, since the upgrade will result in a short downtime
  • There is a backup or snapshot of the current release

Upgrade from Digital Access Admin

 Log in to Digital Access Admin
  1. Log in to Digital Access Admin with an administrator account.
 Download new version
  1. If there are newer versions, the upgrade button is marked red. Click Upgrade. Newer versions are shown.
  2. Download the latest version.
    The new version is downloaded in the background. You can log out, and the download will proceed. The download normally takes a few minutes, depending on your internet connection. When the download is finished, Status is set to Ready
 Upgrade new version
  1. For the downloaded version, click Upgrade.
  2. Click Yes to confirm the upgrade. When you confirm the upgrade, the system will be out of service for a short while. The services are turned off, the configuration data is migrated to the new version, and the system is rebooted. 
 Publish updates
  1. Log in to Digital Access Admin with an administrator account.
    The Upgrade button is not marked red anymore. The Publish button is marked blue, because the configuration data has been migrated.
  2. Click Publish. The upgrade is done. 

Upgrade from console

Digital Access component can be upgraded from the console (v-apps or command line), for example when the deployment is distributed. For distributed deployment of Digital Access component, there are several appliances with different services, and the administrator interface is only available on the node hosting the administration service. On the other nodes, upgrade using the console instead. It can be done directly in the console or through ssh, for example. 

Upgrade using v-apps within virtual appliance

When Digital Access component is deployed as virtual appliance, the console menu v-apps is included. You can use v-apps to configure, for example, the upgrade. 

 Log on to console
  1. Log in to the console (v-apps) with User Name: agadmin.
 Download new version
  1. Select 3) Upgrade System
  2. Select 1) Download
    Available newer versions are displayed. Select the latest version. Download starts. Progress and estimated time left is shown. 
 Upgrade to new version
  1. Select 3) upgrade ([downloaded new version])
  2. Do you want to continue? (y/n). Confirm by typing "y"
    When you confirm the upgrade, the system will be out of service for a short while. The services are turned off, the configuration data is migrated to the new version, and the system is rebooted.
 Publish updates
  1. When the reboot is finished, on the node hosting the admin service, log on to the administration interface and click Publish

Upgrade using command line with Orchestrator

If Digital Access component was deployed using Orchestrator, see Deploy Digital Access component on Docker, the upgrade can be done using command line on the Docker host system. 

 Log on to console
  1. Log in to command line of the Docker host.
 Upgrade to new version

Upgrade using the following commands:

  1. List available upgrade versions.

    List available upgrade versions
    docker exec orchestrator hagcli -o list
  2. Download the wanted version.

    Download wanted version
    docker exec orchestrator hagcli -o download -t x.x.x
  3. Check that the downloaded version is available.

    Check if download available
    docker exec orchestrator hagcli -o version-to-upgrade
  4. Upgrade.

    Upgrade
    docker exec orchestrator hagcli -o upgrade -t x.x.x
 Publish updates
  1. When the reboot is finished, on the node hosting the admin service, log on to the administration interface and click Publish

Offline Docker upgrade

 Offline Docker upgrade

You must extend the disc size of the second partition before you can upgrade to version 6.0.0 or 6.0.1. See instructions under heading "Additional steps for a specific version".


  1. Login as root user and export images using the command docker save.

    docker save repo.nexusgroup.com/smartid-digitalaccess/authentication-service > authentication.tar 
    docker save repo.nexusgroup.com/smartid-digitalaccess/distribution-service > distribution.tar 
    docker save repo.nexusgroup.com/smartid-digitalaccess/policy-service > policy.tar       
    docker save repo.nexusgroup.com/smartid-digitalaccess/administration-service > administration.tar 
    docker save repo.nexusgroup.com/smartid-digitalaccess/access-point > access.tar 
  2. Copy the extracted tar files to the machine that needs to be upgraded.
  3. Load the Digital Access service archived images.

    docker load -i administration-service6.0.1.tar
    docker load -i policy-service6.0.1.tar
    docker load -i authentication-service6.0.1.tar
    docker load -i access-point6.0.1.tar
    docker load -i distribution-service6.0.1.tar 
  4. Verify whether the Orchestrator container is up. If it is not, then use systemctl start orchestrator.
  5. To upgrade the imported version of Digital Access, go to v-apps and select the upgrade menu.

Additional steps for a specific version

Starting from version 6.0.0, Digital Access component will use the Docker technology to run its services. The virtual appliance will act as a Docker host. Future upgrade will only be done on the Docker containers itself, not the virtual appliance. 

Upgrading from a version 5.13.5 to above, Digital Access component needs to be upgraded to version 6.0.0 or 6.0.2 in between. 

It is recommended to upgrade to version 6.0.2.

Upgrade from 5.13.5 to above

 Expand size of second partition


You must extend the disc size of the second partition before upgrade.

Follow the instructions to increase the size of the second partition: 

  1. Boot the virtual machine and login to it.
  2. To find out which hard disk to expand, do df -h to see which disk is mounted, /dev/sdc1 or /dev/sdb1.

    Check which hard disk to expand
    df -h
  3. Shutdown the virtual machine and expand the size of the virtual machine's disk from 4GB to minimum 8GB via editing the VM settings.
    Also:
    • If /dev/sdb1 is mounted, then it is hard disk 3 (which is secondary disk) that must be extended, see step 4.
    • If /dev/sdc1 is mounted, then it is hard disk 2 (which is secondary disk) that must be extended, see step 5.
  4. Follow these steps if /dev/sdb1 is mounted.

     If /dev/sdb1 is mounted
    • List available disks and space.

      List disks and space
      fdisk -l

      You will see the following output:

      /dev/sdb - 4 gb  
      /dev/sdc - 8 gb 
    • Mount the new disk space.

      Mount disk space
      fdisk /dev/sdc
    • Follow the wizard and use these commands:  

      1. d - delete partition
      2. n - create new partition
        1. Select default value for Partition type
        2. Select default value for Partition number
        3. Select default value for First sector
        4. Select default value for Last sector
        5. Select Y to remove the Signature
      3. a - toggle boot flag
      4. w - write changes
    • Create a new file system:

      It is very important that you enter the command exactly as this, with all special characters, for example the character ^.  Also, do not copy and paste the command, as this can couse problems, instead enter it.

      Create file system
      mkfs.ext4 -O ^64bit -L ag-secondary /dev/sdc1
    • Done. Upgrade Digital Access component now. After upgrade, you can check available space again:

      df -h
  5. Follow these steps If /dev/sdc1 is mounted.

     If /dev/sdc1 is mounted
    • List available disks and space.

      List disks and space
      fdisk -l

      You will see the following output:

      /dev/sdb - 8 gb  
      /dev/sdc - 4 gb 
    • Mount the new disk space.

      Mount disk space
      fdisk /dev/sdb
    • Follow the wizard and use these commands:  

      1. d - delete partition
      2. n - create new partition
        1. Select default value for Partition type
        2. Select default value for Partition number
        3. Select default value for First sector
        4. Select default value for Last sector
        5. Select Y to remove the Signature
      3. a - toggle boot flag
      4. w - write changes
    • Create a new file system:

      It is very important that you enter the command exactly as this, with all special characters, for example the character ^. Also, do not copy and paste the command, as this can couse problems, instead enter it.

      Create file system
      mkfs.ext4 -O ^64bit -L ag-secondary /dev/sdb1
    • Done. Upgrade Digital Access component now. After upgrade, you can check available space again:

      df -h
 Endpoint identification

Digital Access component now supports endpoint identification during secure interactions with the user storage, due to an update of the Java version. It must be ensured that the certificate is compliant with the fully qualified domain name (FDQN) which is configured in Digital Access component. For more information, see Adapt Hybrid Access Gateway for endpoint identification.

Upgrade from 6.0.0 to 6.0.2

 Upgrade from 6.0.0 and to 6.0.2

If the virtual appliance has been upgraded from an older version to 6.0.0, follow these steps before you can upgrade to 6.0.2:

  1. Do df -h and check that, if primary disk space consumed is greater than secondary disk size (4 GB by default) then extend the secondary disk to size ~1 GB in excess of size of the root directory on appliance.
  2. Follow the instructions above under heading "Expand size of second partition".

Upgrade from 6.0.0 to 6.0.1

 Upgrade from 5.13.x to 6.0.0 and to 6.0.1

If the virtual appliance has been upgraded from an older version to 6.0.0, follow these steps before you can upgrade to 6.0.1:

  1. Do df -h and check that, if primary disk space consumed is greater than secondary disk size (4 GB by default) then extend the secondary disk to size ~1 GB in excess of size of the root directory on appliance.
  2. Follow the instructions above under heading "Expand size of second partition". 

    Do not upgrade to 6.0.1 until you have followed all instructions below.

  3. Continue with the steps in "Upgrade from 6.0.0 to 6.0.1.
 Upgrade from 6.0.0 to 6.0.1

From Digital Access 6.0.1 and onward, Orchestrator version 1.0.1 needs to be used. Follow these steps to upgrade Orchestrator:

 Upgrade Orchestrator
  1. Stop all Containers.

    sudo docker exec orchestrator hagcli -s all -o stop 
  2. Stop orchestrator.

    systemctl stop orchestrator 
  3. Pull new Orchestrator image with tag 1.0.1

    docker pull repo.nexusgroup.com/smartid-digitalaccess/orchestrator:1.0.1
  4. Pull new Postgres Image

    docker pull repo.nexusgroup.com/smartid-digitalaccess/postgres:9.6-alpine
  5. Delete old Orchestrator and Postgres images

    docker rmi crcommondevelopment92007.azurecr.io/nexus-hag/orchestrator:1.0.0
    
    docker rmi crcommondevelopment92007.azurecr.io/nexus-hag/postgres:9.6-alpine
  6. Change orchestrator tag in file /etc/hag-release to 1.0.1 and Add DOCKER_REPO URL.

    HAG_ORCHESTRATOR_TAG=1.0.1

    DOCKER_REPO=repo.nexusgroup.com

  7. Change Orchestrator image name in the file /etc/systemd/system/orchestrator.service as follows:

    Only change the value of the variable "ExecStart" as provided below.

    Change value of ExecStart
    ExecStart=/usr/bin/docker run --rm -t --name ${SERVICE} -v /etc/hag-release:/etc/hag-release --network=host -v /var/run/docker.sock:/var/run/docker.sock -v /etc/localtime:/etc/localtime -v /etc/timezone:/etc/timezone -v /opt/nexus:/opt/nexus -v /var/lib/postgresql:/var/lib/postgresql -e LOGLEVEL=INFO --log-opt max-size=10m ${DOCKER_REPO}/smartid-digitalaccess/${SERVICE}:${HAG_ORCHESTRATOR_TAG}


  8. Reload the updated orchestrator.service, run 

    systemctl daemon-reload
  9. Start Orchestrator, run

    systemctl start orchestrator
  10. Orchestrator container should now be running and you can continue to upgrade from v-apps or Digital Access Admin.
  1. After that, continue to upgrade the virtual appliance to 6.0.1 from v-apps or Digital Access Admin as described in this article.
  2. For offline docker upgrade only: 

    After adding disk space, you must run the script manually to merge volume:

    Run this command: sudo /usr/bin/boot-tool.sh –e

This article is valid for Digital Access 6.0.2.

Related information