Configuration
Credentials
In order to communicate with the Intersight API, isctl requires authentication credentials. You can use either API Key authentication (API Key ID and Secret Key) or OAuth authentication (Client ID and Client Secret).
There are multiple ways for these to be provided to isctl such as environment variables, configuration file or in the command line arguments. These are the configuration items that determine how isctl communicates with the Intersight API:
Authentication Methods (Choose One)
API Key Authentication:
- Intersight API Key ID - The API Key ID generated by Intersight when a new API key is created in the UI.
- Intersight Secret Key - the private key component (Secret Key) of the API Key created through the Intersight UI. This configuration item can either be the path/filename of the key stored on disk (e.g. ~/intersight.pem) or it can be the key data itself (e.g. -----BEGIN RSA PRIVATE KEY-----\n...).
OAuth Authentication:
- Intersight Client ID - The Client ID for your OAuth app.
- Intersight Client Secret - The Client Secret for your OAuth app.
- Intersight Token URL - The URL to obtain the OAuth token. Defaults to https://<Intersight FQDN>/iam/token if not specified. Generally you will not need to set this.
1Password Integration
Instead of storing credentials in plain text, any of the credential configuration items (API Key ID, Secret Key, Client ID and Client Secret) can be set to a 1Password secret reference of the form op://<vault>/<item>/<field>. isctl will resolve these references using the 1Password CLI (op inject, with all references resolved in a single call), so op must be installed and signed in (or integrated with the 1Password desktop app).
For example, in ~/.isctl.yaml:
intersight_api_key_id: op://Private/Intersight/key_id
intersight_secret_key: op://Private/Intersight/secret_key
Secret references work in the configuration file, environment variables and command line flags. If op is not in your PATH, set the ISCTL_OP_PATH environment variable to the path of the op binary.
Note: For the Secret Key, the 1Password field should contain the private key data itself (not a filename). It can be stored as a multi-line field or as a single-line field (where the newlines have been converted to spaces).
Alternatively, you can use op run to inject secrets into environment variables, e.g. INTERSIGHT_SECRET_KEY=op://Private/Intersight/secret_key op run -- isctl get ntp policy.
Token Caching (OAuth Only)
When using OAuth authentication, isctl caches the access token to disk to avoid fetching a new token on every invocation. This significantly improves performance when running many sequential commands.
- Token Cache Path - Path to the token cache file. Defaults to
$XDG_CONFIG_HOME/isctl/token-cache.jsonor~/.config/isctl/token-cache.jsonifXDG_CONFIG_HOMEis not set. - Disable Token Cache - Set to
trueto disable token caching. Useful for CI environments where you don't want tokens persisted to disk.
General Configuration
- Intersight FQDN - Fully Qualified Domain Name of the Intersight service. For SaaS this will be
intersight.com(and this is the default if not specified) but for Private Virtual Appliance (PVA) or Connected Virtual Appliance (CVA) installations you will need to set this. - Intersight Insecure - if set to true,
isctlwill not verify the certificate of the Intersight API service. If set to false (the default), the Intersight API service certificate will be verified. - Intersight Proxy - The URL of an HTTP proxy to use for API requests (e.g.
http://proxy.example.com:8080). - Intersight TLS Handshake Timeout - Maximum time to wait for the TLS handshake with the Intersight API service (or proxy). Accepts a number of seconds (e.g.
30) or a duration (e.g.30s,1m). Defaults to 10 seconds. Increase this if you seenet/http: TLS handshake timeouterrors. - Readable MoRefs - if set to true, MoRef values in output will use human-readable identity fields (e.g.,
MoRef:organization.Organization[Name:default]) instead of opaque Moid hex strings. The identity fields used depend on each class's identity constraints. Falls back to Moid for classes with no identity constraints. See Readable MoRefs for details.
Configuration Sources
The following table shows the available configuration sources and the configuration items. The sources are listed in precedence order, from highest precedence to lowest precedence:
| Source | API Key ID | Secret Key | Client ID | Client Secret | Token URL | FQDN | Insecure |
|---|---|---|---|---|---|---|---|
| Command Line Flags | --intersight-api-key-id |
--intersight-secret-key |
--intersight-client-id |
--intersight-client-secret |
--intersight-token-url |
--intersight-fqdn |
--insecure |
| Environment Variables | INTERSIGHT_API_KEY_ID |
INTERSIGHT_SECRET_KEY |
INTERSIGHT_CLIENT_ID |
INTERSIGHT_CLIENT_SECRET |
INTERSIGHT_TOKEN_URL |
INTERSIGHT_FQDN |
<not supported> |
| Configuration file | intersight_api_key_id |
intersight_secret_key |
intersight_client_id |
intersight_client_secret |
intersight_token_url |
intersight_fqdn |
intersight_insecure |
| Source | Token Cache Path | Disable Token Cache |
|---|---|---|
| Command Line Flags | --intersight-token-cache-path |
--intersight-disable-token-cache |
| Environment Variables | INTERSIGHT_TOKEN_CACHE_PATH |
INTERSIGHT_DISABLE_TOKEN_CACHE |
| Configuration file | intersight_token_cache_path |
intersight_disable_token_cache |
| Source | Readable MoRefs |
|---|---|
| Command Line Flags | --readable-morefs |
| Configuration file | readable_morefs |
| Source | TLS Handshake Timeout |
|---|---|
| Command Line Flags | <not supported> |
| Environment Variables | INTERSIGHT_TLS_HANDSHAKE_TIMEOUT |
| Configuration file | intersight_tls_handshake_timeout |
Note: Environment variables are case-insensitive.