smartos-live

The nictagadm tool is used to manage SmartOS nic tags. Nic tags allow you to refer to a physical network interface (NIC) using a logical name instead of its MAC address or interface name. These tags are used by vmadm(8) and the SmartOS configuration file as identifiers.

Key Behaviors:

• MTU Management: The MTU of the physical device is set to the maximum MTU specified across all associated nic tags. Note that the MTU is not updated live; it requires a system start to apply.
• Persistence: On nodes with /usbkey present, nictagadm updates /usbkey/config and attempts to update the original USB key to ensure tags persist across reboots. On nodes without /usbkey, tags must be passed as boot parameters to persist.
• Etherstubs: Using the -l flag creates an etherstub, which is a virtual switch on the local host.

The piadm(8) command is used to manage SmartOS Platform Images (PIs) and boot images on ZFS pools. It allows for installing, activating, listing, and destroying platform images.

Note on Verbosity:

• Use -v before a command for verbose output.
• Use -vv before a command for verbose output plus the shell's -x flag (showing all commands run by the script).

The fwadm tool is used to manage firewall data on a SmartOS system, specifically focusing on firewall rules and remote VMs.

Core Concepts

• Firewall Rules: These are JSON objects containing a rule written in a Domain-Specific Language (DSL). Rules only apply to VMs where the firewall_enabled property is set to true.
• Scoping:
  • Rules with an owner_uuid are scoped to VMs with a matching owner.
  • Global rules (ownerless) apply to all VMs described in their targets.
• Remote VMs: JSON objects representing VMs on other SmartOS hosts. They allow rules to reference external entities.
• Automatic Reloading: Adding, updating, or deleting firewall rules or remote VMs will automatically reload the firewalls of any affected VMs.

The imgadm tool is used to import and manage virtual machine images on a SmartOS system. These images (often called 'datasets') are snapshots of pre-installed virtual machines designed for repeated deployment.

An image consists of two parts:

1. A compressed ZFS snapshot (either a ZFS filesystem for OS-level zones or a ZFS zvol for KVM VMs).
2. A JSON manifest containing metadata describing the contents.

Images are primarily identified by a unique UUID.

The mdata-client tools allow guests (SmartOS Zones or KVM virtual machines) to retrieve and manipulate metadata provided by the SmartOS or SmartDataCenter (SDC) hypervisor. The hypervisor provides a set of base metadata keys, but guests can also interact with arbitrary user-provided metadata.

Available Commands

• mdata-list: Lists custom metadata keys currently in the metadata store.
• mdata-get: Retrieves the value associated with a specific metadata key.
• mdata-put: Sets the value for a specific metadata key.
• mdata-delete: Removes a metadata key from the store.

The vminfo(8) tool is a client utility used to interface with the vminfod service via its HTTP interface. It is primarily intended for administrators to check service health and status interactively.

Note: This tool is not intended for stable programmatic use. For automation or programmatic access to vminfod, use the vmadm(8) command or the vminfod/client Node.js library instead.

The vmadm tool is the primary interface for interacting with virtual machines on a SmartOS system. You can use it to create, inspect, modify, and delete virtual machines on the local system. Most operations are performed using the VM's UUID as the primary reference. SmartOS includes bash tab-completion rules for UUIDs to simplify command entry.

Note on LX VMs: Support for LX VMs is currently limited and experimental. Functionality may change significantly without notice, and documentation for LX-specific features is currently incomplete. However, most properties applicable to OS VMs also apply to LX VMs.

/usr/vm/sbin/vmadm <command> [-d] [-v] [command-specific arguments]

SmartOS is composed of several distinct parts managed within the smartos-live repository:

• smartos-live: The root repository containing build logic and SmartOS-specific tools like vmadm and imgadm.
• illumos-joyent: The core operating system (kernel, libraries, and user commands). It is located in projects/illumos and must be used instead of stock illumos-gate.
• illumos-extra: Third-party software (e.g., GNU binutils, OpenSSL, bash, curl, Node.js) maintained via patches applied to stock releases. It is located in projects/illumos-extra.
• Local Projects: Extra projects located in projects/local/ (e.g., illumos-kvm, mdata-client) that implement specific Makefile targets.

The vmadmd daemon runs in a SmartOS global zone to support the vmadm(8) command. It manages long-running tasks and state changes that a single CLI execution cannot handle, such as maintaining connections or waiting for timeouts.

Key responsibilities include:

• KVM Autobooting: Automatically starting KVM VMs based on zone properties.
• VNC Console Exposure: Redirecting internal VM VNC unix sockets to TCP sockets for external access.
• Stop/Reboot Management: Handling timeouts to ensure VMs eventually stop or reboot even if the guest kernel is unresponsive.
• QMP Command Proxying: Exposing QEMU Machine Protocol commands via an HTTP interface.

The daemon exposes these functions through an HTTP server listening on the unix socket /tmp/vmadmd.http. This interface is private and intended for use by vmadm(8).

Public Interfaces

When modifying a standard command, library function, or mapfile section, evaluate backwards compatibility:

1. Test old binaries against the new library.
2. Test shell scripts that rely on specific command output formats.
3. Check against relevant industry standards.

Mapfiles

• Public Mapfiles: Do not add public mapfile versions directly to illumos-joyent. They should be contributed via illumos-gate.
• Private Mapfiles: If a library is specific to illumos-joyent, it may be versioned privately before being moved to a public version upon upstreaming to illumos.