The Agctl Command-Line Interface (CLI) is a command-line tool that facilitates users to trigger operations on an airgap appliance.

For example, user can use the CLI to:

  • Trigger data synchronization between remote repositories and airgap appliance.
  • Check the real time status of data operations.
  • Run selfcheck of appliance against system, network, and data integrity.
  • Reconfig/upgrade appliance.
  • Create a support bundle.
  • Cancel active jobs any time.

Command List

Commands and subcommands

The agctl CLI includes the following commands:
Command Sub-command Comments
sync - Sync data from remote repositories
status Check sync status and progress
export - Export data to local tar.gz bundle
import - Import data from local tar.gz bundle
rsync - Sync data from another airgap appliance
selfcheck data Validate image integrity of local harbor
system Validate local system resource usage
remote Validate connectivity to remote repositories
all Perform above three validations together
show readyz Return each build image readiness information in YAML
status - Check real-time ansible session status
deploy - Customize the system with new configurations
upgrade - Upgrade Photon OS and services
techsupport - Generate tech support bundle
cancel - Cancel running ansible jobs

Global Flags

Use -h, --help to print out help information.

Configurations

Agctl CLI reads an user inputs file, /usr/local/airgap/scripts/vars/user-inputs.yml, which contains all configurations for operations. The user needs to revise the configuration file with customized values before kicking off an operation. Detailed configurations required for each operation will be available in the examples section below.

Examples

agctl sync

The agctl sync group contains two commands, sync and sync status.

Usage

Sync operation will fetch OCI images and helm charts from public registries to local harbor installed in airgap appliance, and download photon repo packages from official photon web site to save in local disk as well.
 agctl sync 
 agctl sync status   

Configuration

User needs to specify required TCA releases and build for sync:
products:
  - name: "tca"
    versions: "2.3.0-3.1.1"
build_sync: "3.1.1-12345678"
local_only: False
keep_bom: False
retry_times: 3
Config Key Default Value Description Example
name tca Product for image sync, supports TCA only
versions 2.3.0-3.1.1 Product releases to sync, by default to sync releases of 2.3.0, 3.0.0, 3.1.0, and 3.1.1. Supports specified value to each release or combination of multiple releases

2.3.0

or

3.1.1

or

2.3.0-3.1.0

build_sync 3.1.1-12345678 Specified TCA build to sync. Format <ver>-<build>, default build number 12345678

3.1.1-87654321

or

3.1.0-23636884

local_only False Syncs images only from local bom files under /usr/local/airgap/bom folder local_only: True
keep_bom False Keep existing bom files in /usr/local/airgap/bom folder after synchronization completed keep_bom: True
retry_times 3 Number of times user can retry when failed to download an image retry_times: 8

Example

  • To sync images for specified TCA releases and TCA build after modified user-inputs.yml, initiate the operation:
    agctl sync
  • To check image sync progress and status:
    agctl sync status

agctl export

The agctl export group contains one command, export.

Usage

agctl export 

Configuration

User needs to specify required TCA releases and build for export, along with an alternative option to enable incremental export by uncommenting photon baseline key and setting specified value:
products:
  - name: "tca"
    versions: "2.3.0-3.1.1"
 #  - name: "photon"
 #    baseline: "2.3.0"

build_sync: "3.1.1-12345678"
keep_bom: False
retry_times: 3
Config Key Default Value Description Example
name tca Product for image sync, supports TCA only tca
versions 2.3.0-3.1.1 Product releases to sync, by default to sync releases of 2.3.0, 3.0.0, 3.1.0 and 3.1.1. Supports specified value to each release or combination of multiple releases

2.3.0

or

3.1.1

or

2.3.0-3.1.0

name photon Parameter for export, supports photon only now photon
baseline 2.3.0 Set baseline for incremental export, default to start from 2.3.0 release baseline

2.3.0

or

3.0.0

build_sync 3.1.1-12345678 Specified TCA build to sync. Format <ver>-<build>, default build number 12345678

3.1.1-87654321

or

3.1.0-23636884

keep_bom False Keep existing bom files in /usr/local/airgap/bom folder keep_bom: True
retry_times 3 Number of times user can retry when failed to download an image retry_times: 8

Example

To export images for specified TCA releases and TCA build, after modified user-inputs.yml, initiate the operation:
agctl export

agctl import

The agctl import group contains one command, import.

Usage
 agctl import 

Configuration

Before executing the import, the user needs to double-check if the server_fqdn set in user-inputs.yml is the same as host’s hostname. Also the user needs to download the bundle for import and put it under the /photon-reps folder.
server_fqdn: tca-ag-1.example.com
Config Key Default Value Description Example
server_fqdn Set by user when deploy OVA Server FQDN

tca-ag-1.example.com

Example

To import data bundle, double-check user-inputs.yml for value of server_fqdn, download bundle for import and put it under /photon-reps, then initiate the operation, agctl import.

agctl rsync

The agctl rsync group contains one command, rsync.

Usage

agctl rsync

Configuration

Before executing the rsync, the user needs to modify values specified for rsync in user-inputs.yml:
remote_server_fqdn: tca-ag-1.example.com
endpoint_name: remote_registry_001
username: admin
secret: Harbor12345
remote_server_cert_file: /usr/local/airgap/certs/remote_registry_001_ca.crt
reg_des: remote harbor registry as source
policy_des: new policy for replication
policy_name: policy1
cron: 0 */30 * * * *
Config Key Default Value Description Example
remote_server_fqdn tca-ag-1.example.com Remote server FQDN

tca-ag-1.example.com

endpoint_name remote_registry_001 Customized endpoint name

remote_registry_001

username admin Remote server harbor username, default set to admin user

admin

or

airgapadmin

secret Harbor12345 Remote server harbor user credential, default set to default harbor admin password

Harbor12345

or

Harbor54321

remote_server_cert_file /usr/local/airgap/certs/remote_registry_001_ca.crt Path to remote server harbor ca certificate

/root/remote_ca.crt

reg_des remote harbor registry as source Description of remote harbor
policy_des new policy for replication Description of new policy for harbor replication
policy_name policy1 Customized policy name
cron 0 */30 * * * * Schedule to trigger harbor replication, default set to sync per 30 minutes

Example

To trigger remote sync, modify above values in user-inputs.yml, initiate the operation: agctl rsync.

agctl selfcheck

The agctl selfcheck group contains four commands, data, system, remote, and all.

Usage
agctl selfcheck data
agctl selfcheck system
agctl selfcheck remote
agctl selfcheck all 

Configuration

Before executing the selfcheck, the user needs to double check if the server_fqdn set in user-inputs.yml is the same as the host's hostname.
server_fqdn: tca-ag-1.example.com
Config Key Default Value Description Example
server_fqdn Set by user when deploy OVA Server FQDN

tca-ag-1.example.com

Example

To trigger selfcheck, double-check user-inputs.yml for the value of server_fqdn, then initiate the operation.
  • To perform a data integrity validation: agctl selfcheck data.
  • To check Photon OS real time resource usage: agctl selfcheck system.
  • To test connectivity to remote repositories: agctl selfcheck remote.
  • To perform all above three tests together: agctl selfcheck all.

agctl show

The agctl show group contains one command, readyz.

Usage

agctl show readyz 

Configuration

Before executing the show, readyz, the user needs to double-check if the server_fqdn set in user-inputs.yml is the same as the host's hostname.
server_fqdn: tca-ag-1.example.com
Config Key Default Value Description Example
server_fqdn Set by user when deploying OVA Server FQDN

tca-ag-1.example.com

Example

To trigger show, readyz, double-check server_fqdn value in user-inputs.yml, initiate the operation: agctl show readyz.

agctl status

The agctl status group contains one command, status.

Usage
agctl status

Configuration

No configuration required for status command.

Example

To trigger status, initiate the operation: agctl status.

agctl deploy

The agctl deploy group contains one command, deploy.

Usage
agctl deploy

Configuration

Caution: Deploying operation will revise system configurations which may lead to inaccessibility of services or discontinued support to kubernetes clusters’ lifecycle. Carefully set values in user-inputs.yml and ensure you fully understand your purpose to execute deploy. 
Before executing the deploy, the user needs to modify values in user-inputs.yml.
server_fqdn: tca-ag-1.example.com
ip_family: ipv4
iface_name: eth0
dhcp: True
static_ip: 192.168.2.100/24
default_gw: 192.168.2.1
dns_servers: 192.168.100.100

enable_proxy: False
http_proxy: http://proxy.example.com:8118
https_proxy: http://proxy.example.com:8118
no_proxy: 192.168.1.0/24,tca-ag-1.example.com
proxy_ca_cert_path: /root/certs/proxy_ca.crt

auto_generate: True
cert_ca_common_name: example.com
cert_country_name: US
cert_state_name: CA
cert_county: PA
cert_organization: VMW
cert_bu: SDE

server_cert_path: /root/certs/tca-ag-1.example.com.cert
server_cert_key_path: /root/certs/tca-ag-1.example.com.key
ca_cert_path: /root/certs/ca.crt

harbor_http_port: 8001
harbor_https_port: 8043
Config Key Default Value Description Example
server_fqdn Set by user when deploy OVA Server hostname, ensure that the name can be resolved by DNS

tca-ag-1.example.com

ip_family Set by user when deploy OVA IP family set for airgap appliance. Support value: ipv4/ipv6/ipv6,ipv4 ipv6, ipv4
iface_name Set by user when deploy OVA NIC name used to configure IP address information eth0
dhcp Set by user when deploy OVA If use DHCP address for airgap appliance False
static_ip Set by user when deploy OVA IP address, either IPv4, IPv6, or both, if DHCP is enabled, static IP settings will not take effects 192.168.1.1/24
default_gw Set by user when deploy OVA Gateway setting. Either IPv4, IPv6, or both, if DHCP is enabled, static IP settings will not take effects 192.168.1.253
dns_servers Set by user when deploy OVA DNS hosted in a local environment. Either IPv4, IPv6, or both, if DHCP is enabled, static IP settings will not take effects 192.168.1.1
enable_proxy Set by user when deploy OVA If set proxy when deploy False
http_proxy Set by user when deploy OVA http proxy server info

http://proxy.example.com:3128

https_proxy Set by user when deploy OVA Https proxy server info

https://proxy.example.com:3443

no_proxy Set by user when deploy OVA Host list which their traffics are not go through proxy server

192.168.1.0/24,tca-ag-1.example.com

proxy_ca_cert_path Set by user when deploy OVA Path to proxy ca certificate file

/root/certs/proxy_ca.crt

auto_generate Set by user when deploy OVA Whether to generate new certificate False
cert_ca_common_name Set by user when deploy OVA Common name to generate new cert, takes effect when auto_generate is set to True

example.com

cert_country_name Set by user when deploy OVA Country info for new cert. Allows 2 characters only. Take effect when auto_generate is set to True US
cert_state_name Set by user when deploy OVA State info for new cert. Takes effect when auto_generate is set to True MyState
cert_county Set by user when deploy OVA County info for new cert. Takes effect when auto_generate is set to True MyCounty
cert_organization Set by user when deploy OVA Organization name for new cert. Takes effect when auto_generate is set to True MyOrg
cert_bu Set by user when deploy OVA Business Unit info for new cert. Takes effect when auto_generate is set to True MyBu
server_cert_path Set by user when deploy OVA Path to user provided certificate. Takes effect when auto_generate is set to False

/root/certs/tca-ag-1.example.com.cert

server_cert_key_path Set by user when deploy OVA Path to user provided certificate key file. Takes effect when auto_generate is set to False

/root/certs/tca-ag-1.example.com.key

ca_cert_path Set by user when deploy OVA Path to user provided CA certificate file. Take effect when auto_generate is set to False

/root/certs/ca.crt

harbor_http_port Set by user when deploy OVA 8001 8088
harbor_https_port Set by user when deploy OVA 8043 8843

Example

To trigger deploy, modify above values in user-inputs.yml and initiate the operation: agctl deploy.

agctl upgrade

The agctl upgrade group contains one command, upgrade.

Usage
 agctl upgrade

Configuration

Before executing the upgrade, the user needs to download the upgrade ISO and revise user-inputs.yml.
local_iso_path: /data/update.iso
skip_snapshot: no
Config Key Default Value Description Example
local_iso_path /data/update.iso Path to upgrade ISO file /data/new-update.iso
skip_snapshot no Whether to skip taking a system snapshot. If set to yes, the upgrade is not revertible yes

Example

To upgrade system, download the upgrade ISO to target path, edit user-inputs.yml, initiate the operation: agctl upgrade.

agctl techsupport

The agctl techsupport group contains one command, techsupport.

Usage
 agctl techsupport 

Configuration

No configuration required for techsupport command.

Example

To generate techsupport bundle, initiate the operation: agctl techsupport.

agctl cancel

The agctl cancel group contains one command, cancel.

Usage
agctl cancel

Configuration

No configuration required for cancel command.

Example

To cancel running ansible session, just launch the operation: agctl cancel.