You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/agent/internal/startup/startup.go

516 lines
18 KiB
Go

// Package startup defines the immutable first-boot contract for cloud images.
//
// A startup script is part of a VM create operation, not a general VM setting.
// The script is copied into a NoCloud seed and a small guest-side runner marks
// the attempt before executing it. Consequently a failed (or interrupted)
// first attempt is observable, but is not silently replayed by a later seed
// refresh or reboot.
package startup
import (
"bytes"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"strings"
"unicode"
"unicode/utf8"
)
const (
// MaxScriptBytes is the maximum UTF-8 encoded size of a startup script.
// The limit is deliberately measured after CRLF normalization because the
// guest receives the normalized document.
MaxScriptBytes = 32 * 1024
// NoCloud file names are fixed by the datasource contract.
UserDataFilename = "user-data"
MetaDataFilename = "meta-data"
NetworkConfigFilename = "network-config"
// Guest paths are kept stable so a seed refresh cannot create a second
// runner or lose the execution evidence from an earlier attempt.
ScriptPath = "/var/lib/virt-cloud/startup.sh"
RunnerPath = "/var/lib/virt-cloud/startup-runner.sh"
StateDirPath = "/var/lib/virt-cloud/startup"
StartedMarkerPath = "/var/lib/virt-cloud/startup/started"
OutputLogPath = "/var/lib/virt-cloud/startup/output.log"
ExitCodePath = "/var/lib/virt-cloud/startup/exit-code"
// DefaultNetworkConfig is a valid, deterministic NoCloud network document
// for callers that do not need to configure an interface in this phase.
DefaultNetworkConfig = "{\"ethernets\":{},\"version\":2}\n"
// MaxFileBytes and MaxSeedBytes mirror the bounded cloud-init seed
// contract. They apply to encoded bytes on the wire, not decoded script
// characters.
MaxFileBytes = 256 * 1024
MaxSeedBytes = 1024 * 1024
)
const (
// OperationCreate is the only operation allowed to carry a startup script.
OperationCreate = "create"
)
var (
ErrInvalidScript = errors.New("invalid startup script")
ErrScriptCreateOnly = errors.New("startup script is allowed only for create")
ErrInvalidSeed = errors.New("invalid NoCloud seed")
ErrOperationRequired = errors.New("seed operation is required")
)
// RunnerScript is installed in a guest only when a non-empty POSIX sh script is
// present on a create seed. The marker directory is created atomically before
// invoking the user script. If the script exits non-zero or is interrupted,
// the marker remains and future invocations return without replaying it.
const RunnerScript = "#!/bin/sh\n" +
"umask 077\n" +
"state=/var/lib/virt-cloud/startup\n" +
"mkdir -p \"$state\" || exit 1\n" +
"if ! mkdir \"$state/started\" 2>/dev/null; then\n" +
" [ -d \"$state/started\" ] && exit 0\n" +
" exit 1\n" +
"fi\n" +
"/bin/sh /var/lib/virt-cloud/startup.sh > \"$state/output.log\" 2>&1\n" +
"result=$?\n" +
"printf '%s\\n' \"$result\" > \"$state/exit-code\"\n" +
"exit \"$result\"\n"
// SeedRequest contains the create-time inputs used to render the three
// NoCloud seed files. NetworkConfig is a JSON object encoded as a string; the
// generated file is canonical, ASCII JSON so cloud-init sees one stable byte
// representation regardless of caller whitespace.
// StartupScript is interpreted by the guest's POSIX /bin/sh; callers must not
// rely on Bash-only syntax or a script shebang to select another interpreter.
//
// Operation must be non-empty. StartupScript must be empty for every
// operation except OperationCreate; rejecting it is safer than silently
// dropping a script that a caller thought would run.
type SeedRequest struct {
Operation string
InstanceID string
Hostname string
NetworkConfig string
StartupScript string
}
// SeedFiles is the in-memory representation of a NoCloud seed. The artifact
// writer in artifact.go publishes a directory without invoking an ISO tool;
// any later image/ISO backend remains outside this content renderer.
type SeedFiles struct {
UserData []byte
MetaData []byte
NetworkConfig []byte
StartupScriptIncluded bool
}
// NormalizeScript validates and canonicalizes a script for guest injection.
// CRLF is normalized to LF; lone CR bytes are preserved as script content.
func NormalizeScript(script string) (string, error) {
if !utf8.ValidString(script) {
return "", fmt.Errorf("%w: script must be valid UTF-8", ErrInvalidScript)
}
if strings.IndexByte(script, 0) >= 0 {
return "", fmt.Errorf("%w: script must not contain NUL", ErrInvalidScript)
}
normalized := strings.ReplaceAll(script, "\r\n", "\n")
if len([]byte(normalized)) > MaxScriptBytes {
return "", fmt.Errorf("%w: script exceeds %d bytes", ErrInvalidScript, MaxScriptBytes)
}
return normalized, nil
}
// ValidateScript is the validation-only form of NormalizeScript.
func ValidateScript(script string) error {
_, err := NormalizeScript(script)
return err
}
// ScriptForOperation applies the create-only dispatch rule and returns the
// normalized content that may be placed in a seed. Empty scripts are valid
// for all operations and produce no runner files.
func ScriptForOperation(operation, script string) (string, error) {
normalized, err := NormalizeScript(script)
if err != nil {
return "", err
}
if operation != OperationCreate && normalized != "" {
return "", fmt.Errorf("%w: operation %q", ErrScriptCreateOnly, operation)
}
return normalized, nil
}
// BuildCreateSeed renders a create seed and is the preferred entry point for
// provisioning code. It makes the create-only startup contract explicit at
// the call site.
func BuildCreateSeed(instanceID, hostname, networkConfig, script string) (SeedFiles, error) {
return BuildSeed(SeedRequest{
Operation: OperationCreate,
InstanceID: instanceID,
Hostname: hostname,
NetworkConfig: networkConfig,
StartupScript: script,
})
}
// BuildSeed deterministically renders user-data, meta-data, and
// network-config. It does not create an ISO or write to disk.
func BuildSeed(request SeedRequest) (SeedFiles, error) {
if err := Validate(request); err != nil {
return SeedFiles{}, err
}
normalizedScript, err := ScriptForOperation(request.Operation, request.StartupScript)
if err != nil {
return SeedFiles{}, err
}
userData, err := renderUserData(normalizedScript)
if err != nil {
return SeedFiles{}, err
}
metaData, err := marshalJSONASCII(metadataDocument{
InstanceID: request.InstanceID,
LocalHostname: request.Hostname,
})
if err != nil {
return SeedFiles{}, fmt.Errorf("marshal meta-data: %w", err)
}
networkConfig, err := canonicalizeJSONDocument(request.NetworkConfig)
if err != nil {
return SeedFiles{}, err
}
files := SeedFiles{
UserData: userData,
MetaData: append(metaData, '\n'),
NetworkConfig: []byte(networkConfig),
StartupScriptIncluded: request.Operation == OperationCreate && normalizedScript != "",
}
if err := files.Validate(); err != nil {
return SeedFiles{}, err
}
return files, nil
}
// Validate checks all request fields without rendering a seed. It is useful
// at the panel/agent boundary before accepting an operation into a journal.
func Validate(request SeedRequest) error {
if strings.TrimSpace(request.Operation) == "" {
return ErrOperationRequired
}
if err := validateMetadataScalar("instance ID", request.InstanceID); err != nil {
return err
}
if err := validateMetadataScalar("hostname", request.Hostname); err != nil {
return err
}
if _, err := ScriptForOperation(request.Operation, request.StartupScript); err != nil {
return err
}
if request.NetworkConfig != "" {
if !utf8.ValidString(request.NetworkConfig) {
return fmt.Errorf("%w: network config must be valid UTF-8", ErrInvalidSeed)
}
if strings.IndexByte(request.NetworkConfig, 0) >= 0 {
return fmt.Errorf("%w: network config must not contain NUL", ErrInvalidSeed)
}
if _, err := canonicalizeJSONDocument(request.NetworkConfig); err != nil {
return err
}
}
return nil
}
// Validate verifies the basic NoCloud file invariants, including the bounded
// ASCII-JSON wire format used by the image/cloud-init adapter.
func (files SeedFiles) Validate() error {
if len(files.UserData) == 0 || len(files.MetaData) == 0 || len(files.NetworkConfig) == 0 {
return fmt.Errorf("%w: all NoCloud files are required", ErrInvalidSeed)
}
if len(files.UserData) > MaxFileBytes || len(files.MetaData) > MaxFileBytes || len(files.NetworkConfig) > MaxFileBytes {
return fmt.Errorf("%w: a NoCloud file exceeds %d bytes", ErrInvalidSeed, MaxFileBytes)
}
if len(files.UserData)+len(files.MetaData)+len(files.NetworkConfig) > MaxSeedBytes {
return fmt.Errorf("%w: NoCloud files exceed %d bytes in total", ErrInvalidSeed, MaxSeedBytes)
}
for name, content := range map[string][]byte{
UserDataFilename: files.UserData,
MetaDataFilename: files.MetaData,
NetworkConfigFilename: files.NetworkConfig,
} {
if !utf8.Valid(content) {
return fmt.Errorf("%w: %s must be valid UTF-8", ErrInvalidSeed, name)
}
if !isASCII(content) {
return fmt.Errorf("%w: %s must contain ASCII JSON bytes", ErrInvalidSeed, name)
}
if bytes.IndexByte(content, 0) >= 0 {
return fmt.Errorf("%w: %s must not contain NUL", ErrInvalidSeed, name)
}
if bytes.Contains(content, []byte("\r\n")) {
return fmt.Errorf("%w: %s must use LF line endings", ErrInvalidSeed, name)
}
if content[len(content)-1] != '\n' {
return fmt.Errorf("%w: %s must end with a newline", ErrInvalidSeed, name)
}
}
if !bytes.HasPrefix(files.UserData, []byte("#cloud-config\n")) {
return fmt.Errorf("%w: user-data must begin with #cloud-config", ErrInvalidSeed)
}
if !validJSONObjectDocument(files.UserData[len("#cloud-config\n"):]) {
return fmt.Errorf("%w: user-data JSON is invalid", ErrInvalidSeed)
}
if !validJSONObjectDocument(files.MetaData) || !validJSONObjectDocument(files.NetworkConfig) {
return fmt.Errorf("%w: metadata and network-config must be JSON", ErrInvalidSeed)
}
startupContract, err := inspectStartupContract(files.UserData)
if err != nil {
return err
}
if startupContract.Included != files.StartupScriptIncluded {
return fmt.Errorf("%w: startup runner inclusion flag does not match user-data", ErrInvalidSeed)
}
return nil
}
// ShouldRun reports whether the guest runner should execute the script. A
// marker is created before execution, so both successful and failed attempts
// return false on every subsequent invocation.
func ShouldRun(markerPresent bool) bool { return !markerPresent }
func renderUserData(script string) ([]byte, error) {
config := struct {
WriteFiles []writeFile `json:"write_files,omitempty"`
RunCommand [][]string `json:"runcmd,omitempty"`
}{}
if script != "" {
config.WriteFiles = []writeFile{
{Path: ScriptPath, Content: script, Owner: "root:root", Permissions: "0600"},
{Path: RunnerPath, Content: RunnerScript, Owner: "root:root", Permissions: "0700"},
}
config.RunCommand = [][]string{{"/bin/sh", RunnerPath}}
}
encoded, err := marshalJSONASCII(config)
if err != nil {
return nil, fmt.Errorf("marshal user-data: %w", err)
}
return append([]byte("#cloud-config\n"), append(encoded, '\n')...), nil
}
type writeFile struct {
Path string `json:"path"`
Content string `json:"content"`
Owner string `json:"owner"`
Permissions string `json:"permissions"`
}
type startupContractDetails struct {
Included bool
ScriptSHA256 string
}
// inspectStartupContract parses the generated cloud-config instead of using
// byte-string presence checks. A tenant-provided note, script body, or other
// arbitrary JSON value may mention the fixed guest paths, but that must never
// make first_boot_present true. The only accepted startup shape is exactly one
// private script file, exactly one fixed runner file, and one exact /bin/sh
// command invoking that runner.
func inspectStartupContract(userData []byte) (startupContractDetails, error) {
if !bytes.HasPrefix(userData, []byte("#cloud-config\n")) {
return startupContractDetails{}, fmt.Errorf("%w: user-data must begin with #cloud-config", ErrInvalidSeed)
}
var document map[string]json.RawMessage
if err := decodeStrictJSON(userData[len("#cloud-config\n"):], &document); err != nil {
return startupContractDetails{}, fmt.Errorf("%w: user-data JSON could not be inspected", ErrInvalidSeed)
}
writeFiles, _, err := decodeOptionalStrict[[]writeFile](document, "write_files")
if err != nil {
return startupContractDetails{}, fmt.Errorf("%w: write_files has invalid shape", ErrInvalidSeed)
}
runCommands, _, err := decodeOptionalStrict[[][]string](document, "runcmd")
if err != nil {
return startupContractDetails{}, fmt.Errorf("%w: runcmd has invalid shape", ErrInvalidSeed)
}
scriptIndex := -1
runnerIndex := -1
for index, file := range writeFiles {
switch file.Path {
case ScriptPath:
if scriptIndex >= 0 || file.Owner != "root:root" || file.Permissions != "0600" || file.Content == "" {
return startupContractDetails{}, fmt.Errorf("%w: startup script write_file is not canonical", ErrInvalidSeed)
}
normalized, normalizeErr := NormalizeScript(file.Content)
if normalizeErr != nil || normalized != file.Content {
return startupContractDetails{}, fmt.Errorf("%w: startup script write_file is not normalized", ErrInvalidSeed)
}
scriptIndex = index
case RunnerPath:
if runnerIndex >= 0 || file.Owner != "root:root" || file.Permissions != "0700" || file.Content != RunnerScript {
return startupContractDetails{}, fmt.Errorf("%w: startup runner write_file is not canonical", ErrInvalidSeed)
}
runnerIndex = index
}
}
runnerCommandCount := 0
for _, command := range runCommands {
if len(command) == 0 {
return startupContractDetails{}, fmt.Errorf("%w: runcmd contains an empty command", ErrInvalidSeed)
}
mentionsRunner := false
for _, argument := range command {
if argument == RunnerPath {
mentionsRunner = true
}
}
if mentionsRunner {
if len(command) != 2 || command[0] != "/bin/sh" || command[1] != RunnerPath {
return startupContractDetails{}, fmt.Errorf("%w: startup runner command is not canonical", ErrInvalidSeed)
}
runnerCommandCount++
}
}
if scriptIndex < 0 && runnerIndex < 0 && runnerCommandCount == 0 {
return startupContractDetails{ScriptSHA256: digestScript(nil)}, nil
}
if scriptIndex < 0 || runnerIndex < 0 || runnerCommandCount != 1 {
return startupContractDetails{}, fmt.Errorf("%w: startup runner files or command are incomplete", ErrInvalidSeed)
}
return startupContractDetails{Included: true, ScriptSHA256: digestScript([]byte(writeFiles[scriptIndex].Content))}, nil
}
func digestScript(content []byte) string {
sum := sha256.Sum256(content)
return hex.EncodeToString(sum[:])
}
func decodeStrictJSON(data []byte, destination any) error {
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.DisallowUnknownFields()
if err := decoder.Decode(destination); err != nil {
return err
}
var trailing any
if err := decoder.Decode(&trailing); !errors.Is(err, io.EOF) {
if err == nil {
return errors.New("multiple JSON values")
}
return err
}
return nil
}
func decodeOptionalStrict[T any](document map[string]json.RawMessage, key string) (T, bool, error) {
var zero T
raw, ok := document[key]
if !ok {
return zero, false, nil
}
var value T
if err := decodeStrictJSON(raw, &value); err != nil {
return zero, true, err
}
return value, true, nil
}
type metadataDocument struct {
InstanceID string `json:"instance-id"`
LocalHostname string `json:"local-hostname"`
}
func validateMetadataScalar(label, value string) error {
if value == "" {
return fmt.Errorf("%w: %s is required", ErrInvalidSeed, label)
}
if !utf8.ValidString(value) {
return fmt.Errorf("%w: %s must be valid UTF-8", ErrInvalidSeed, label)
}
for _, r := range value {
if r == 0 || r == '\r' || r == '\n' || unicode.IsControl(r) {
return fmt.Errorf("%w: %s contains a control character", ErrInvalidSeed, label)
}
}
if strings.TrimSpace(value) != value {
return fmt.Errorf("%w: %s must not have leading or trailing whitespace", ErrInvalidSeed, label)
}
return nil
}
func canonicalizeJSONDocument(document string) (string, error) {
if document == "" {
return DefaultNetworkConfig, nil
}
document = strings.ReplaceAll(document, "\r\n", "\n")
var value any
if err := json.Unmarshal([]byte(document), &value); err != nil {
return "", fmt.Errorf("%w: network config must be JSON: %v", ErrInvalidSeed, err)
}
if value == nil {
return "", fmt.Errorf("%w: network config must be a JSON object", ErrInvalidSeed)
}
if _, ok := value.(map[string]any); !ok {
return "", fmt.Errorf("%w: network config must be a JSON object", ErrInvalidSeed)
}
encoded, err := marshalJSONASCII(value)
if err != nil {
return "", fmt.Errorf("%w: encode network config: %v", ErrInvalidSeed, err)
}
return string(append(encoded, '\n')), nil
}
// marshalJSONASCII is the Go equivalent of Python's json.dumps(...,
// ensure_ascii=True) used by the previous seed implementation. Keeping all
// three files ASCII makes the seed contract unambiguous across cloud-init
// versions while JSON decoding still restores the original UTF-8 script.
func marshalJSONASCII(value any) ([]byte, error) {
encoded, err := json.Marshal(value)
if err != nil {
return nil, err
}
var output bytes.Buffer
output.Grow(len(encoded))
for len(encoded) > 0 {
r, size := utf8.DecodeRune(encoded)
if r == utf8.RuneError && size == 1 {
return nil, fmt.Errorf("json encoder returned invalid UTF-8")
}
if r <= 0x7f {
_, _ = output.Write(encoded[:size])
} else if r <= 0xffff {
_, _ = fmt.Fprintf(&output, "\\u%04x", r)
} else {
// JSON represents non-BMP runes as a UTF-16 surrogate pair.
r -= 0x10000
high := 0xd800 + (r >> 10)
low := 0xdc00 + (r & 0x3ff)
_, _ = fmt.Fprintf(&output, "\\u%04x\\u%04x", high, low)
}
encoded = encoded[size:]
}
return output.Bytes(), nil
}
func validJSONObjectDocument(content []byte) bool {
content = bytes.TrimSuffix(content, []byte{'\n'})
if len(content) == 0 || !isASCII(content) {
return false
}
var value map[string]any
return json.Unmarshal(content, &value) == nil && value != nil
}
func isASCII(content []byte) bool {
for _, b := range content {
if b > 0x7f {
return false
}
}
return true
}