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
| 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
agctl sync agctl sync status
Configuration
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
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
agctl export
agctl import
The agctl import group contains one command, import.
agctl import
Configuration
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
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.
agctl selfcheck data agctl selfcheck system agctl selfcheck remote agctl selfcheck all
Configuration
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 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
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.
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.
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, initiate the operation: agctl deploy.
agctl upgrade
The agctl upgrade group contains one command, upgrade.
agctl upgrade
Configuration
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.
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.
agctl cancel
Configuration
No configuration required for cancel command.
Example
To cancel running ansible session, just kick off the operation: agctl cancel.
