sdpctl Quick Start Guide

# Step 1: Extract the executable

# Step 2: Required if you are using self-signed cert on Admin UI, otherwise skip
  Download the CA cert from the Admin UI, System, Certificate Authority
  Place the downloaded cert file in the same folder as the sdpctl binary


# Step 3: Provide the Admin UI url
> sdpctl.exe configure
# or
> sdpctl.exe configure --pem <ca-cert-file-name>
  ? Enter the url for the Controller API (example https://controller.company.com:8443) https://ag-ctrl.company.com:8443
  Configuration updated successfully


# Step 4: Sign in to your Collective
> sdpctl.exe configure signin
  ? Choose a provider:  [Use arrows to move, type to filter]
  ❯ Azure AD SAML Admin
    Azure AD OIDC
    local

  ? Please enter your one-time password: ******
  Successfully signed in


# Step 5: Verify the configuration
> sdpctl.exe appliance status
  Name                    Status     Function      CPU     Memory    Network out/in           Disk    Version
  ----                    ------     --------      ---     ------    --------------           ----    -------
  Singapore Controller    healthy    Controller    1.4%    13.9%     34.9 Kbps / 17.1 Kbps    1.7%    6.0.1+30125
  Singapore Gateway       healthy    Gateway       0.3%    12.7%     0.64 Kbps / 0.12 Kbps    0.9%    6.0.1+30125


# Step 5: Optionally, check the Completion command to enable command completion for your shell for convenience
          

# Step 1: Prepare the upgrade
> sdpctl.exe appliance upgrade prepare --image=<upgrade-image-zip-or-url>
  PREPARE SUMMARY

  ...
  ? Do you want to continue? Yes

  [2022-09-27T15:04:01+02:00] Preparing image on appliances:
    ✓ Singapore Controller: ready
    ✓ Singapore Gateway: ready

  [2022-09-27T15:05:09+02:00] PREPARE COMPLETE


# Step 2: Backup then complete the upgrade
> sdpctl.exe appliance upgrade complete
  ? Do you want to backup before proceeding? Yes
  ? Path to where backup should be saved /Users/ann.gills/Downloads/appgate/backup
  ? select appliances to backup: Singapore Controller ( Controller )

  UPGRADE COMPLETE SUMMARY

  Appliances will be upgraded to version 6.0.2+30473

  ...

  [2022-09-27T15:07:56+02:00] Upgrading primary controller:
  ✓ Singapore Controller: upgraded

  [2022-09-27T15:11:18+02:00] Upgrading additional appliances (Batch 1 / 1):
  ✓ Singapore Gateway: upgraded

  [2022-09-27T15:14:25+02:00] UPGRADE COMPLETE

  Appliance               Upgraded to
  ---------               -----------
  Singapore Controller    6.0.2+30473
  Singapore Gateway       6.0.2+30473
          

> sdpctl.exe appliance backup
  ? select appliances to backup:  [Use arrows to move, space to select,  to all,  to none, type to filter]
  ❯ [ ]  Singapore Controller ( Controller )
    [ ]  Singapore Gateway ( Gateway )

  Will perform backup on the following appliances:
    - Singapore Controller

  Backup destination is /Users/ann.gills/Downloads/appgate/backup

    ✓ Singapore Controller: download complete

  Backup complete!

  # use cz-restore script internal to the appliance to restore the backup file
          

# list distinguished names with active tokens
> sdpctl.exe token list
  Distinguished Name                     Device ID       Last Token Issued At           Provider Name    Username
  ------------------                     ---------       --------------------           -------------    --------
  CN=2cc1a54a...,CN=ann.gills,OU=ldap    2cc1a54a-...    2022-11-22T09:42:09.738773Z    ldap             ann.gills
  ...


# renew all tokens for ann.gills
> sdpctl.exe token revoke "CN=2cc1a54...,CN=ann.gills,OU=ldap"
  ID           Type            Distinguished Name                   Issued          Expires         Revoked  Site ID    Site Name   Revocation Time
  --           ----            ------------------                   ------          -------         -------  -------    ---------   ---------------
  e9abaff5...  Entitlement     CN=2cc1a54a...,CN=ann.gills,OU=ldap  2022-11-22 ...  2022-11-23 ...  true      8a4add    SG-01       2022-11-22 ...
  d9910d8d...  Claims          CN=2cc1a54a...,CN=ann.gills,OU=ldap  2022-11-22 ...  2022-11-23 ...  true                            2022-11-22 ...


# renew all entitlement tokens
> sdpctl.exe token revoke --by-token-type entitlement
  ID           Type            Distinguished Name                   Issued          Expires         Revoked  Site ID    Site Name   Revocation Time
  --           ----            ------------------                   ------          -------         -------  -------    ---------   ---------------
  e9abaff5...  Entitlement     CN=2cc1a54a...,CN=ann.gills,OU=ldap  2022-11-22 ...  2022-11-23 ...  true      8a4add    SG-01       2022-11-22 ...
  ...
          

# you can manage multiple Collectives by adding more admin profiles

# configure your production SDP Collective
> sdpctl.exe configure
  ? Enter the url for the Controller API (example https://controller.company.com:8443) https://production.company.com:8443
  Configuration updated successfully


# by default there are no profiles created
> sdpctl.exe profile list
no profiles added


# create a new profile for staging
> sdpctl.exe profile add staging
  Created profile staging, run 'sdpctl profile list' to see all available profiles
  run 'sdpctl profile set staging' to select the new profile


# note that at this point, sdpctl is still using the "default" profile


> sdpctl.exe profile list
  Current profile is default (/Users/ann.gills/Library/Application Support/sdpctl/profiles/default) primary production.company.com

  Available profiles
  Name       Config directory
  ----       ----------------
  default    /Users/ann.gills/Library/Application Support/sdpctl/profiles/default
  staging    /Users/ann.gills/Library/Application Support/sdpctl/profiles/staging


# set the staging profile as current
> sdpctl.exe profile set staging
  staging (/Users/ann.gills/Library/Application Support/sdpctl/profiles/staging) is selected as current sdp profile


# now, sdpctl is still using the "staging" profile


# configure your staging SDP Collectice
> sdpctl.exe configure
  ? Enter the url for the Controller API (example https://controller.company.com:8443) https://staging.company.com:8443
  Configuration updated successfully

> sdpctl.exe profile list
  Current profile is staging (/Users/ann.gills/Library/Application Support/sdpctl/profiles/staging) primary controller staging.company.com

  Available profiles
  Name       Config directory
  ----       ----------------
  default    /Users/ann.gills/Library/Application Support/sdpctl/profiles/default
  staging    /Users/ann.gills/Library/Application Support/sdpctl/profiles/staging


# once you are done with managin staging Collective, you can switch back to default
# set the default profile as current
> sdpctl.exe profile set default
  staging (/Users/ann.gills/Library/Application Support/sdpctl/profiles/default) is selected as current sdp profile
          

# you can run sdpctl unattended using the environment variables.

# list available environment variables
> sdpctl.exe help environment
  ...
  SDPCTL_USERNAME=admin
  SDPCTL_PASSWORD=password
  SDPCTL_URL=https://controller.company.com:8443
  ...


# once environment variables set, backup the controller sdpctl is pointing at
> sdpctl.exe appliance backup --current --quiet
  ✓ Controller  Singapore Controller: download complete
  Backup complete!