wscript API: Lab and Segment

This chapter is the method-by-method reference for the two handles a script starts from: Lab, which every script receives, and Segment, which a lab handle gives out by name. The scripting guide explains where scripts run and how a provision reaches the machines it needs; the networking guide explains what the segment rules do on the wire. The machine handle is in wscript API: Machine, and the terminal handle, the record types and the module functions are in wscript API: Term, types and the vmlab module.

Every script begins with use vmlab. A provision script or an ad-hoc vmlab script run defines fn main(lab: Lab); an event handler defines fn handle(event: Event, lab: Lab). Both handles are opaque: they carry no fields, only methods. Every method that can fail returns a wscript Result whose error is a string, and an error that propagates out of main fails the provision run and therefore vmlab up. The signatures below use the parameter names the host registers; the generated vmlab.wscripti interface file spells them a0, a1 and so on.

Lab.name

The lab's name, as the lab file declares it.

fn name(self) -> string

Returns the name from the lab "<name>" {} block. It never fails.

fn main(lab: Lab) {
    lab.log("provisioning lab " + lab.name())
}

Lab.log

Write one line to the lab log and to the terminal of the CLI that started the run.

fn log(self, msg: string)

The line goes to lab.log under the lab's state directory (see Files and directories) and is streamed live to the vmlab up or vmlab script invocation that is running the script. From an event handler it lands in the lab log only. It never fails.

fn main(lab: Lab) {
    for m in lab.machines() {
        lab.log(m.name() + ": " + m.state())
    }
}

Lab.machine

The handle for one machine of either kind, by name.

fn machine(self, name: string) -> Result[Machine, string]

Returns a Machine handle running as the agent identity. The error names the machine when the lab declares none by that name. Use this when the script does not care which kind it is talking to; an event handler that reads event.vm usually does not.

fn handle(event: Event, lab: Lab) {
    if event.name == "container.crashed" {
        let Ok(m) = lab.machine(event.vm) else { return }
        let started = m.start()
    }
}

Lab.machines

Every machine in the lab, VMs and containers alike.

fn machines(self) -> List[Machine]

Returns one handle per declared machine. The order is the runtime's own and is not the declaration order. It never fails; an empty lab returns an empty list.

fn main(lab: Lab) {
    for m in lab.machines() {
        let r = m.wait_ready(300)
    }
}

Lab.vm

The handle for one VM, by name, refusing a container.

fn vm(self, name: string) -> Result[Machine, string]

The same handle Lab.machine returns, with a kind check in front. A name the lab does not declare fails as Lab.machine does. A name that is a container fails with a message saying so and pointing at lab.container(), which tells you more than "no such machine" would. Every operation on the returned handle is available on containers too; the check exists only so a script that knows what it declared reads well.

fn main(lab: Lab) {
    let Ok(dc) = lab.vm("dc01") else {
        lab.log("no dc01")
        return
    }
    let r = dc.wait_ready(600)
}

Lab.this_vm

The machine whose provision block declared the running script.

fn this_vm(self) -> Result[Machine, string]

Set for a provision {} block declared inside a vm {} or container {}, and for a template's first-boot script, where it is the build VM. It fails with a message saying so from an event handler and from vmlab script, because neither has an owning machine.

Inside a template first-boot script the handle it returns is gated: on that handle, is_ready and wait_ready mean "the agent answers" rather than full readiness, because full readiness is unreachable until the script itself returns. See Machine.is_ready.

fn main(lab: Lab) {
    let vm = lab.this_vm().expect("no target vm")
    match vm.exec("hostname", []) {
        Ok(r) => lab.log("running on " + r.stdout),
        Err(e) => lab.log("exec failed: " + e),
    }
}

Lab.vms

The VMs of the lab, and only the VMs.

fn vms(self) -> List[Machine]

Lab.machines filtered to machines whose kind is vm. It never fails.

fn main(lab: Lab) {
    for vm in lab.vms() {
        let s = vm.snapshot("baseline")
    }
}

Lab.container

The handle for one container, by name, refusing a VM.

fn container(self, name: string) -> Result[Machine, string]

The mirror of Lab.vm: the same handle, with the opposite kind check. A VM's name fails with a message pointing at lab.vm(). See lab containers for what a container can and cannot do at call time.

fn main(lab: Lab) {
    let Ok(web) = lab.container("web") else { return }
    match web.logs(50) {
        Ok(text) => lab.log(text),
        Err(e) => lab.log(e),
    }
}

Lab.containers

The containers of the lab, and only the containers.

fn containers(self) -> List[Machine]

Lab.machines filtered to machines whose kind is container. It never fails.

fn main(lab: Lab) {
    for c in lab.containers() {
        if !c.is_healthy() { lab.log(c.name() + " is unhealthy") }
    }
}

Lab.segment

The handle for one segment, by name.

fn segment(self, name: string) -> Result[Segment, string]

The error names the segment and the lab when no segment of that name is assembled. A handle is a name, not a lock: every method on it looks the segment up again, so a segment torn down after the handle was taken fails on the next call with "segment is gone".

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let id = lan.dns_set("intranet.corp.local", "10.0.0.10")
}

Segment.name

The segment's name.

fn name(self) -> string

Returns the name the handle was taken with. It never fails.

fn main(lab: Lab) {
    let Ok(seg) = lab.segment("lan") else { return }
    lab.log("rules on " + seg.name())
}

Segment.dns_set

Add a static DNS record, or a wildcard, to the segment's zone.

fn dns_set(self, name: string, ip: string) -> Result[int, string]

Returns a rule id for Segment.dns_clear. An exact name becomes a static record that replaces any earlier record for that name; a pattern beginning with *. becomes a wildcard. Lookup precedence in the zone is sinkhole, then exact record, then wildcard, then the upstream forwarder, else NXDOMAIN.

It fails when ip does not parse as an IPv4 address, when the segment is gone, or when the segment has DNS disabled.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    match lan.dns_set("*.apps.corp.local", "10.0.0.20") {
        Ok(id) => lab.log("wildcard rule " + id),
        Err(e) => lab.log(e),
    }
}

Segment.dns_sinkhole

Answer NXDOMAIN for every name matching a pattern.

fn dns_sinkhole(self, pattern: string) -> Result[int, string]

Returns a rule id for Segment.dns_clear. Sinkholes win over every other kind of record; among sinkholes the most specific pattern wins and declaration order breaks ties. The script surface always sinks with NXDOMAIN; the other sinkhole modes are available in the lab file only, see lab and segment. It fails on a gone segment or one with DNS disabled.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let id = lan.dns_sinkhole("*.telemetry.example.com")
}

Segment.dns_clear

Remove a rule added by Segment.dns_set or Segment.dns_sinkhole.

fn dns_clear(self, rule_id: int) -> Result[bool, string]

Returns true when something was removed and false when the id matched nothing. Records the lab file declared have no id and cannot be cleared from a script. It fails on a gone segment or one with DNS disabled.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let Ok(id) = lan.dns_sinkhole("updates.example.com") else { return }
    let removed = lan.dns_clear(id)
}

Segment.block

Drop every packet to a destination address or range.

fn block(self, cidr: string) -> Result[int, string]

Returns a rule id for Segment.unblock. The rule applies to every protocol and port. It fails when cidr is neither a network nor an address, when the segment is gone, or when the segment runs no network services, which is the case for a global segment the supervisor gateways.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    match lan.block("203.0.113.0/24") {
        Ok(id) => lab.log("block rule " + id),
        Err(e) => lab.log(e),
    }
}

Segment.block_port

Drop packets to a destination for one protocol and port.

fn block_port(self, cidr: string, proto: string, port: int) -> Result[int, string]

Returns a rule id for Segment.unblock. It fails on a malformed cidr, an unknown proto, a port out of range, a gone segment, or a segment without network services.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let id = lan.block_port("0.0.0.0/0", "tcp", 25)
}

Segment.unblock

Remove a block or redirect rule by id.

fn unblock(self, rule_id: int) -> Result[bool, string]

Returns true when a rule was removed and false when nothing carried that id. Despite the name it removes redirects too; the block and redirect tables share one id space. It fails on a gone segment or one without network services.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let Ok(id) = lan.block("198.51.100.7") else { return }
    vmlab::sleep_ms(30000)
    let gone = lan.unblock(id)
}

Segment.redirect

Rewrite the destination of packets from one address to another.

fn redirect(self, from: string, to: string) -> Result[int, string]

Returns a rule id that Segment.unblock removes. Redirects are evaluated before blocks. The script surface leaves the protocol unset, so the rule matches every protocol; a protocol-specific redirect is declared in the lab file. It fails when either endpoint has a malformed IP or port, or on a gone segment or one without network services.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let id = lan.redirect("8.8.8.8:53", "10.0.0.1:53")
}

Segment.forward

Publish a guest TCP port on the host.

fn forward(self, host_port: int, vm: string, guest_port: int) -> Result[int, string]

Returns the forward's id. The forward is TCP only and is resolved once: the machine's first agent-reported IPv4 address at the time of the call, so the machine must be up and leased. It fails when either port is out of range, when the machine does not exist, when the agent reports no IPv4 address yet, when the segment has no NAT (a forward needs egress to originate the guest-side connection), when the host port is already in use, including by a forward the lab file declares, or on a gone segment or one without network services. Forwards the lab file declares are computed up front instead; see networking.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let Ok(web) = lab.container("web") else { return }
    let r = web.wait_ready(120)
    let id = lan.forward(8080, "web", 80)
}

Segment.route_to

Connect this segment and another for the daemon to route between, in both directions.

fn route_to(self, other: string) -> Result[unit, string]

The runtime form of routes_to: the pair is the same thing whichever side connects it, and connecting a connected pair is not an error. Routing takes effect at once. Each side offers the other's subnet in DHCP option 121 to leases granted after the call; a guest holding a lease reaches the other side through its default route when that is the daemon's gateway. Fails, naming the segment, when other is not a segment of this lab, is global or either side is, or is this segment. See networking.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    match lan.route_to("dmz") {
        Ok(_) => lab.log("routed"),
        Err(e) => lab.log(e),
    }
}

Segment.unroute_to

Disconnect this segment and another: the daemon stops routing between them, both ways.

fn unroute_to(self, other: string) -> Result[unit, string]

Takes apart a pair connected by either side, including one declared with routes_to. A pair not connected is not an error. Fails as Segment.route_to does for a segment that is unknown, global or this one. Leases granted after the call no longer carry the route.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    let r = lan.unroute_to("dmz")
}

Segment.rules

The segment's live block and redirect rules, as JSON text.

fn rules(self) -> Result[string, string]

Returns a JSON array in evaluation order: redirects first, then blocks, each in insertion order. Every element carries id, kind (redirect or block) and a one-line description. A block also carries cidr, and port when it has one; a redirect carries from and to; either carries proto when it is protocol-specific. Rules from the lab file and rules added by script appear together. DNS rules are not included. It fails on a gone segment or one without network services.

fn main(lab: Lab) {
    let Ok(lan) = lab.segment("lan") else { return }
    match lan.rules() {
        Ok(json) => lab.log(json),
        Err(e) => lab.log(e),
    }
}