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.
516 lines
18 KiB
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
|
|
}
|