Command certificate

Palo Alto Networks SSH Manager · vSSH CLI

vssh certificate

Enroll and renew SSH certificates for applications and hosts. Unlike login, which loads a short-lived credential into your agent for interactive use, certificate writes the private key and certificate to disk so a service or host can use them.

Aliases: c, cert, certificates

Subcommands:

• enroll: request a new certificate.
• renew: renew an existing certificate.

---

vssh certificate enroll

Enroll an SSH certificate for an application or host and write it to disk.

Aliases: e, enrol

vssh certificate enroll [principals] [flags]

Positional arguments

Argument	Description
principals	Comma-separated list of principals for the certificate, for example svc-web,deploy. Equivalent to repeating --principal.

Flags

Flag	Default	Description
--template	(prompt)	Issuance template name. Use * to choose from all templates.
-o, --out-file	Key ID	Base name for the output files.
--owner	current user	File owner as user:group for the written credential.
--create-ssh-config	false	Also write an SSH client config file.
--ssh-config-name	ssh_config	Name of the SSH client config file. Use with --create-ssh-config.
--principal	(none)	Principal for the certificate. Repeatable. --principal alice,bob --principal john gives alice, bob, john.
--key-algorithm	rsa	Algorithm for a locally generated key: rsa, ecdsa, or ed25519.
--key-size-curve	(algorithm default)	Key size or curve: 2048, 3072, 4096, P-256, P-384, P-521.
--passphrase	(none)	Passphrase to protect the generated private key.
--public-key	auto	Public key source. For enroll, auto generates a key locally. You can also pass a file path, local, service, or paste.
--extension	(none)	Certificate extension, for example permit-pty. Repeatable.
--source-address	(none)	Restrict where the certificate may be used from (CIDR). Repeatable.
--force-command	(none)	Force this command to run on connect, ignoring what the client requests.
--validity	template policy	Requested validity period.
--key-id	(none)	Key ID for the certificate.
--object-name	(none)	Object name for the certificate in SSH Manager.
--folder	(none)	Folder (policy path) for the certificate.
--destination-address	(none)	Destination address recorded with the certificate.
--legacy-client	auto-detected	Use only with an SSH client older than OpenSSH 7.3.

Examples

Enroll a certificate for two service principals:

vssh certificate enroll svc-account1,svc-account2 --url https://tpp.example.com

Enroll an ed25519 key for a host, restricted to a subnet and forced to a single command:

vssh certificate enroll deploy \
  --template "Hosts - Deploy" \
  --key-algorithm ed25519 \
  --source-address 10.0.0.0/24 \
  --force-command "/usr/local/bin/deploy-only" \
  --out-file /etc/ssh/deploy_key \
  --owner deploy:deploy

Enroll from a CI job using a JWT:

VSSH_JWT=$CI_JOB_JWT vssh certificate enroll svc-account1 --auth jwt --url https://tpp.example.com

---

vssh certificate renew

Renew an existing SSH certificate and write the new one to disk. By default vSSH checks how much of the current validity has passed and skips the renewal if it is too early. That makes the command safe to run on a schedule.

Aliases: r

vssh certificate renew [cert-file-path] [flags]

Positional arguments

Argument	Description
cert-file-path	Path to the certificate to renew. Equivalent to --file.

Flags

Flag	Default	Description
--file	(required)	Path to the certificate to renew.
--out-file	same as original	Path to store the renewed certificate.
--expires-in	70%	Renew only if this much validity or less remains. Accepts a percentage used (70%) or a duration of remaining life (1d, 2w, 30d). 0 forces renewal.
--force	false	Renew regardless of remaining validity.
--rekey	false	Generate a new key pair for the renewed certificate. Without it, the existing key is reused.
--template	original template	Issuance template to renew from. Defaults to the template that issued the original certificate.
--execute	(none)	Command to run only after a successful renewal, for example to reload a service.
--symlinks-check	auto	Symlink safety check. Set to disabled to turn it off.
--owner	current user	File owner as user:group for the renewed credential.
--acl-user-read-only	(none)	Add a user with read-only access to the credential's ACL.
--acl-user-read-write	(none)	Add a user with read and write access to the credential's ACL.
--create-ssh-config	false	Also write an SSH client config file.
--ssh-config-name	ssh_config	Name of the SSH client config file. Use with --create-ssh-config.

The certificate flags from enroll (--key-algorithm, --key-size-curve, --principal, --extension, --source-address, --validity, --force-command, --key-id, --object-name, --folder, --destination-address) are also accepted. When omitted, renew reuses the values from the existing certificate.

Return code

If the certificate does not need renewal yet, renew exits with code 5 and does not contact the CA. See Understanding return codes. This lets a scheduled job tell "renewed" apart from "not due yet".

Examples

Renew a host certificate if less than 30 days of validity remain:

vssh certificate renew /etc/ssh/ssh_host_ed25519_key-cert.pub --expires-in 30d

Renew, generate a fresh key, and reload the service on success:

vssh certificate renew /etc/ssh/deploy_key-cert.pub \
  --rekey \
  --execute "systemctl reload deploy.service"

Force a renewal now:

vssh certificate renew /etc/ssh/deploy_key-cert.pub --force

Related pages

• Enroll a certificate for an application or host
• Renew a certificate
• Machine identity tutorial
• Securing SSH access