Install shdctl
Install the shdctl command-line tool, configure registry credentials, and review external CLI requirements
阅读时间10 分钟最后更新于 13 天前
Unity provides as part of your Self-Hosted Deployment onboarding package. Every release from 2.0.0 on also includes it under , and Copy the install script shows it in full. To move a deployment of an earlier release from vpctl to shdctl, follow Install shdctl 1.0.0 before you pull instead. After you have the script, run the following command:
install-shdctl.shcommon/scripts/./install-shdctl.sh latest
The following sections explain the script's options, the external CLIs that shdctl uses for specific operations, and how to configure the registry credentials shdctl uses to pull releases.
Requirements
shdctl is a single Go binary; it has no runtime dependencies of its own. External CLIs are required only for operations that shell out to them:
You need... | Required for... |
|---|---|
| The install script ( |
| |
| |
| |
| |
| Only if you want to validate |
shdctl release pullshdctl release generateshdctl secret generateshdctl manifest init/validate/schemashdctl configureInstall the shdctl binary
The install script automatically detects your OS and architecture and downloads the correct binary from the Unity registry.
Before you run the install script, ensure you have:
- ORAS CLI: the install script uses it to pull the shdctl binary, but doesn't install it. For installation instructions, refer to Installation (ORAS).
- Registry credentials: a username and password, which Unity provides.
The script supports interactive mode for users and non-interactive mode for CI and automation.
Interactive mode
-
Run the script without setting credentials. It prompts you for your username and password:./install-shdctl.sh latestYou can also pin a specific version:./install-shdctl.sh 1.1.0
-
Enter your credentials at the prompt:[install-shdctl] Logging in to uccmpprivatecloud.azurecr.io (interactive)...[install-shdctl] Please enter your registry credentials:Username: <your-username>Password: <your-password>
Non-interactive mode for CI and automation
For automated environments, set both and environment variables:
ORAS_USERNAMEORAS_PASSWORDexport ORAS_USERNAME="<your-username>"export ORAS_PASSWORD="<your-password>"./install-shdctl.sh latest
You can also pin a specific version:
export ORAS_USERNAME="<your-username>"export ORAS_PASSWORD="<your-password>"./install-shdctl.sh 1.1.0
Custom installation directory
Specify a custom installation directory as the second argument:
./install-shdctl.sh latest /opt/bin
The script creates a missing directory, with when you cannot create it yourself — as a non-root user, for instance.
sudo/opt/binScript actions
The script performs the following actions:
- Auto-detects your platform (/
linux/darwin) and architecture (windows/amd64). This detection applies to the machine you run shdctl on. The cluster nodes must bearm64. For more information, refer to Node pools.amd64 - Checks whether the CLI is installed. If it isn't, the script exits with a link to the ORAS installation instructions. Install
oras, and then run the script again.oras - Authenticates to the registry by using interactive or non-interactive mode based on environment variables. The login stays in your Docker credential store afterwards; run if you don't want it kept.
oras logout <registry> - Downloads and extracts the correct shdctl binary.
- Installs it to or the directory you specify, using
/usr/local/binto create that directory or copy into it when you cannot.sudo - Links the tool's previous name, , to it (except on Windows), so scripts that still call
vpctlkeep working until shdctl 2.0.0.vpctl - Verifies the installation by running .
shdctl version
Environment variables
Variable | Required | Default | Description |
|---|---|---|---|
| No* | - | Registry username (for non-interactive mode) |
| No* | - | Registry password (for non-interactive mode) |
| No | | Registry URL |
* Both and must be set together for non-interactive mode, or both unset for interactive mode.
ORAS_USERNAMEORAS_PASSWORDConfigure registry credentials
Before you can pull releases, configure your registry credentials.
-
Run the interactive configuration command:shdctl configureThe command prompts you for:
- Username
- Password (input is hidden)
The registry defaults to. To configure credentials for a different registry, pass it as a positional argument:uccmpprivatecloud.azurecr.io.shdctl configure set <registry-url> -
Alternatively, configure credentials non-interactively. The registry argument is positional and defaults to. You can provide the password by using one of the non-interactive methods in Security: providing registry credentials.
uccmpprivatecloud.azurecr.io
Credentials are stored in , readable only by your user (, in a directory) but not encrypted — protect it like any other credential file. Only reads it; uses your Docker credentials instead.
~/.shdctl/config.json06000700shdctl release pullartifact syncSecurity: providing registry credentials
shdctl configure set- — read the password from stdin. Best for CI/CD pipelines:
--password-stdinecho "$REGISTRY_PASSWORD" | shdctl configure set <registry-url> --username "$REGISTRY_USERNAME" --password-stdin - environment variable — non-interactive without piping. Pair with
SHDCTL_PASSWORD. The pre-renameSHDCTL_USERNAMEandVPCTL_USERNAMEare still read, with a deprecation notice, until shdctl 2.0.0:VPCTL_PASSWORDexport SHDCTL_USERNAME=<username>export SHDCTL_PASSWORD=<password>shdctl configure set <registry-url> - Interactive prompt — the default when you run without flags. Password input is hidden.
shdctl configure set <registry-url> - flag — discouraged. The password is exposed in your shell history and in the process list (
--password <value>). shdctl emits a warning to stderr:ps aux
Kept for backward compatibility; not recommended.WARNING: Using --password via the CLI is insecure (visible in shell history and the process list).Use --password-stdin, set SHDCTL_PASSWORD, or omit --password to be prompted interactively.
--password--password-stdinSHDCTL_PASSWORDshdctl configure setTo view or delete stored credentials, and for every subcommand, refer to Manage registry credentials.
configureCopy the install script
If you don't have the onboarding package or a release package, save the following script as , make it executable with , and run it as Install the shdctl binary describes:
install-shdctl.shchmod +x install-shdctl.sh#!/usr/bin/env bash# install-shdctl.sh - Install shdctl from ORAS registry## Usage:# ./install-shdctl.sh <version> [install-dir]## Arguments:# version Required. The shdctl version to install (e.g. 1.0.0, latest)# install-dir Optional. Directory to install shdctl into (default: /usr/local/bin)## Environment variables:# ORAS_REGISTRY Registry URL (default: uccmpprivatecloud.azurecr.io)# ORAS_USERNAME Registry username (optional; if unset, interactive login is used)# ORAS_PASSWORD Registry password (optional; if unset, interactive login is used)## The script auto-detects the current OS and architecture, pulls the# matching shdctl archive from the ORAS registry, and installs it.set -euo pipefail# ── Defaults ──────────────────────────────────────────────────────────ORAS_REGISTRY="${ORAS_REGISTRY:-uccmpprivatecloud.azurecr.io}"INSTALL_DIR="${2:-/usr/local/bin}"# ── Helpers ───────────────────────────────────────────────────────────info() { echo "[install-shdctl] $*"; }error() { echo "[install-shdctl] ERROR: $*" >&2; exit 1; }# ── Validate arguments ───────────────────────────────────────────────VERSION="${1:-}"if [ -z "$VERSION" ]; then echo "Usage: $0 <version> [install-dir]" echo "" echo "Environment variables:" echo " ORAS_REGISTRY Registry URL (default: uccmpprivatecloud.azurecr.io)" echo " ORAS_USERNAME Registry username (optional; prompts interactively if unset)" echo " ORAS_PASSWORD Registry password (optional; prompts interactively if unset)" exit 1fi# Determine login mode: non-interactive (CI) vs interactive (human)if [ -n "${ORAS_USERNAME:-}" ] && [ -n "${ORAS_PASSWORD:-}" ]; then LOGIN_MODE="ci"elif [ -z "${ORAS_USERNAME:-}" ] && [ -z "${ORAS_PASSWORD:-}" ]; then LOGIN_MODE="interactive"else # One is set but not the other — likely a misconfiguration error "Both ORAS_USERNAME and ORAS_PASSWORD must be set for non-interactive login, or both must be unset for interactive login"fi# ── Detect OS ─────────────────────────────────────────────────────────detect_os() { local os os="$(uname -s)" case "$os" in Linux*) echo "linux" ;; Darwin*) echo "darwin" ;; MINGW*|MSYS*|CYGWIN*) echo "windows" ;; *) error "Unsupported operating system: $os" ;; esac}# ── Detect architecture ──────────────────────────────────────────────detect_arch() { local arch arch="$(uname -m)" case "$arch" in x86_64|amd64) echo "amd64" ;; aarch64|arm64) echo "arm64" ;; *) error "Unsupported architecture: $arch" ;; esac}# ── Check ORAS CLI is present ─────────────────────────────────────────ensure_oras() { if command -v oras &>/dev/null; then info "oras already installed: $(oras version 2>/dev/null || echo 'unknown')" return fi error "oras CLI is not installed. Please install it before running this script. Installation instructions: https://oras.land/docs/installation/"}# ── Main ──────────────────────────────────────────────────────────────OS="$(detect_os)"ARCH="$(detect_arch)"info "Detected platform: ${OS}/${ARCH}"info "Installing shdctl v${VERSION} to ${INSTALL_DIR}"# Ensure oras CLI is availableensure_oras# Login to ORAS registryif [ "$LOGIN_MODE" = "ci" ]; then info "Logging in to ${ORAS_REGISTRY} (non-interactive)..." echo "${ORAS_PASSWORD}" | oras login "${ORAS_REGISTRY}" \ --username "${ORAS_USERNAME}" \ --password-stdinelse info "Logging in to ${ORAS_REGISTRY} (interactive)..." info "Please enter your registry credentials:" oras login "${ORAS_REGISTRY}"fi# Prepare temp directory for downloadWORK_DIR="$(mktemp -d)"trap 'rm -rf "$WORK_DIR"' EXIT# Pull from registryORAS_REF="${ORAS_REGISTRY}/releases/cli/shdctl_${OS}_${ARCH}:${VERSION}"info "Pulling ${ORAS_REF}..."oras pull "$ORAS_REF" -o "$WORK_DIR"# Find the archive.# When pulling "latest", the actual filename still contains the original version# (e.g. shdctl_0.3.1_linux_amd64.tar.gz), so we match by extension pattern# rather than exact name.if [ "$OS" = "windows" ]; then ARCHIVE_GLOB="shdctl_*_${OS}_${ARCH}.zip"else ARCHIVE_GLOB="shdctl_*_${OS}_${ARCH}.tar.gz"fiARCHIVE_PATH=$(find "$WORK_DIR" -name "$ARCHIVE_GLOB" -type f 2>/dev/null | head -1)if [ -z "$ARCHIVE_PATH" ]; then error "Could not find archive matching $ARCHIVE_GLOB after pull"fiinfo "Found archive: $(basename "$ARCHIVE_PATH")"# Extractinfo "Extracting archive..."EXTRACT_DIR="$(dirname "$ARCHIVE_PATH")"if [ "$OS" = "windows" ]; then BINARY_NAME="shdctl.exe" unzip -q "$ARCHIVE_PATH" -d "$EXTRACT_DIR"else BINARY_NAME="shdctl" tar -xzf "$ARCHIVE_PATH" -C "$EXTRACT_DIR"fiBINARY_PATH="${EXTRACT_DIR}/${BINARY_NAME}"chmod +x "$BINARY_PATH"# Installinfo "Installing shdctl to ${INSTALL_DIR}..."# A directory under a root-owned parent (/opt/bin as a non-root user) needs sudo# to create, the same way the copy below needs it to write into one.if ! mkdir -p "$INSTALL_DIR" 2>/dev/null; then info "Creating ${INSTALL_DIR} with sudo..." sudo mkdir -p "$INSTALL_DIR"fiif [ -w "$INSTALL_DIR" ]; then mv "$BINARY_PATH" "${INSTALL_DIR}/${BINARY_NAME}"else sudo mv "$BINARY_PATH" "${INSTALL_DIR}/${BINARY_NAME}"fi# Leave the pre-1.0.0 name working through 1.x. A symlink rather than a# copy: shdctl reads argv[0], so a process started through it sees "vpctl" and# prints the deprecation notice, which a second copy of the binary would do just# as well but would also have to be kept in step on every upgrade.# TODO: remove in shdctl 2.0.0.if [ "$OS" != "windows" ]; then LEGACY_PATH="${INSTALL_DIR}/vpctl" info "Linking the previous name ${LEGACY_PATH} -> ${BINARY_NAME} (removed in 2.0.0)" if [ -w "$INSTALL_DIR" ]; then ln -sf "$BINARY_NAME" "$LEGACY_PATH" else sudo ln -sf "$BINARY_NAME" "$LEGACY_PATH" fifi# Verifyinfo "Verifying installation...""${INSTALL_DIR}/${BINARY_NAME}" versioninfo "shdctl v${VERSION} installed successfully at ${INSTALL_DIR}/${BINARY_NAME}"