Edit

Hood

%hood is the system manager and control agent included in the %base desk. It's divided into three modules located in /lib/hood/:

  • %drum: CLI app management. It acts as the middle-man between the Dill vane and the individual CLI apps, including the Dojo itself.

  • %helm: system control. It handles requests for things like sending |his, spawning moons, packing and melding, seting verbosity, etc. It's the middle-man between user commands and the kernel. It's the target of many of the Hood generators (those that begin with |) like |moon, |hi, |verb, etc, and the various vane-specific generators.

  • %kiln: desk updates and filesystem control. It's responsible for tracking and applying desk updates (like when you run |install ~mister-dister-dozzod-dozzod %landscape). It also exposes a number of Clay and filesystem-related actions. It's the target of a number of Hood generators (those that begin with |) like |commit, |install, |mount, |suspend, etc.

While you usually interact with Hood via its generators, its API can also be used by agents, so it's useful to know what its pokes and other endpoints are. We'll look at each module in turn.

Drum

Drum's CLI app management functionality is usally mediated but functions in the /lib/sole.hoon library. We'll not document it here. For more information on CLI apps, you can refer to the Command-Line Apps guide and Building a CLI app example.

Drum's additional API is as follows.

Scries

Our ship

A scry with a path of /x/kiln/our will return our ship as a @p with a %noun mark.

Example:

> .^(@p %gx /=hood=/kiln/our/noun)
~zod

Kernel update blocked?

A scry with a path of /x/kiln/lag will return a ? with a %loob mark specifying whether a kernel upgrade is blocked.

Example:

Base hash

A scry with a path of /x/kiln/base-hash will return the %base base hash as a @uv with a %noun mark.

Example:

Sync source change requests

A scry with a path of /x/kiln/jumps will return the current sync source change requests as an %all $jump with a %kiln-jump mark.

Example:

Syncs

A scry with a path of /x/kiln/syncs will return a map from $sync-record to $sync-state of the currently active desk syncs with a %noun mark.

Example:

Sync sources

A scry with a path of /x/kiln/sources will return a (map desk [ship desk]) of the current syncs with %noun mark.

Example:

Global automerge setting

A scry with a path of /x/kiln/automerge will return a ? saying what the default automerge policy is with a %loob mark.

Example:

Pikes

A scry with a path of /x/kiln/pikes wil return a $pikes of the state of apps with a %kiln-pikes mark.

Example:

Pending syncs

A scry with a path of /x/kiln/pending will return a %pending $sync-update for pending syncs with a %kiln-sync-update mark.

Example:

Set system error verbosity

A poke with a %drum-knob mark will set the verbosity level for %crud error messages generated by the system.

Accepts

  • .tag: should always be %crud, all other tags have no effect.

  • .lev: verbosity level.

Example

Shut down ship

A poke with a %drum-exit mark will shut down the ship.

Accepts

Example

Connect CLI app

A poke with a %drum-link mark will connect the specified CLI app on the specified ship to the Dojo (you can cycle between linked CLI apps with Ctrl+X). Note you can connect to the Dojo of remote ships if they've given you permission by running :dojo|allow-remote-login ~sampel-palnet.

Accepts

  • .ses: terminal session. Typically %$ for the default one.

  • .gyl: the ship and app to link. A (pair ship term) where the $term is the app name.

Example

Disconnect CLI app

A poke with a %drum-unlink mark will unlink a previously linked CLI app.

Accepts

  • .ses: terminal session. Typically %$ for the default one.

  • .gyl: the ship and app to unlink. A (pair ship term) where the $term is the app name.

Example

Write file to Unix

A poke with a %drum-put mark will write the given atom out to the Unix filesystem in <pier>/.urb/put/. It just writes the atom's bytes so is agnostic to the format. Most commonly you'd give it a $cord to write out a text file.

Accepts

  • .pax: the path where the last element is the extension, so /foo/bar/txt is written to <pier>/.urb/put/foo/bar.txt.

  • .arg: either the atom to write or a pair of session ID and the atom to write. If no session ID is given, it'll default to the default session %$, which is typically what you want.

Example

Then in Unix:

Helm

Helm provides an interface for a number of vane tasks. Some of them are generally useful and some are fairly obscure debug functionality. We will document all of them here for completeness.

Reset Ames congestion control

A poke with a %helm-ames-prod mark will reset congestion control in Ames for the specified ship(s).

Accepts

Example

Blacklist/whitelist ships in Ames

A poke with a %helm-ames-snub mark will whitelist or blacklist a list of ships in Ames. Ships on the blacklist or not on the whitelist will have all Ames traffic dropped. Note that this overrides the existing blacklist/whitelist, it's not additive.

Accepts

  • .form: %allow means whitelist, %deny means blacklist. A whitelist means all traffic from sources other than the ships specified will be dropped. A blacklist means traffic from the specified ships will be dropped, and other traffic will be allowed.

  • .ships: The list of ships to whitelist/blacklist.

Example

Filter Ames debug prints

A poke with a %helm-ames-sift mark will turn off Ames verbosity for all but the specified ships. Note this overrides existing per-ship verbosity settings. If the list is empty, it'll just turn on verbosity for all ships. This would be used in combination with %helm-ames-verb to turn on specific Ames debug prints. Without any debug prints turned on, you won't see any difference.

Accepts

Examples

Set Ames verbosity

A poke with a %helm-ames-verb mark will turn on debug prints for specified Ames debug flags. Note this will override any previous settings. An empty list of debug flags will turn off all Ames debug prints.

Accepts

See the $verb:ames entry in the Ames data types reference for details of the different verbosity flags.

Example

Resend timers in Ames

A poke with a %helm-ames-wake mark will tell Ames to set resend timers for any flows that lack them. This was introduced to solve a bug in an old kernel version and is unlikely to be useful.

Accepts

Example

Close stale flows in Ames

A poke with a %helm-ames-kroc mark will close all stale Ames flows for the given list of ship-$bone pairs. If the optional .dry flag is enabled, it won't do anything. This requires a great deal of additional logic to use, and is better left to the |ames/close-flows generator.

As of the directed messaging update in [%zuse 410], Ames no-ops on the %kroc task this poke sends. Therefore, this poke is no longer useful.

Accepts

  • .dry: whether it's a dry run (no-op) or whether the stale flows should actually be closed.

  • .bones: the ship-$bone pairs for which stale flows should be closed.

Adjust congestion control in Ames

A poke with a %helm-ames-cong mark will adjust the congestion control constants in Ames. You shouldn't change these unless you know what you're doing.

Accepts

  • .msg: number of pending messages to be considered clogged (default is 5).

  • .mem: number of pending message fragments to be considered clogged (default is 100.000).

Note that Ames .mem no longer considers .mem in its clog calculations so you should just leave it as the default 100.000.

Example

Print Atom details

A poke with a %helm-atom mark will print source, size and hash information about the given atom.

Accepts

Example

Automatic memory reports

A poke with a mark of %helm-automass will tell Hood to repeatedly run a memory report at the given interval. You can turn it off again with %helm-cancel-automass.

Accepts

  • .recur: the memory report interval. For example, ~m1 would be every 1 minute.

Example

Cancel automatic memory reports

A poke with a mark of %helm-cancel-automass will turn off Automass automatic memory reports.

Accepts

Example

Rotate web login code

A poke with a mark of %helm-code will rotate a ship's web login code. Note all existing web login sessions with be ended, and you'll need to run +code to get the new login code. Note also that cycling the code like this means Bridge can't automatically derive the web login code.

Accepts

  • .act: if it's null it's a no-op, if it's %reset it changes the code.

Example

Approve CORS origin in Eyre

A poke with a mark of %helm-cors-approve will approve the given CORS origin URL.

Accepts

  • .origin: this is a cord containing the fully qualified URL to whitelist for CORS.

Example

Deny CORS origin in Eyre

A poke with a mark of %helm-cors-reject will reject the given CORS origin URL.

Accepts

  • .origin: this is a cord containing the fully qualified URL to whitelist for CORS.

Example

Kill old-style outgoing subscriptions in Gall

A poke with a mark of %helm-doff will kill old-style outgoing subscriptions in Gall. This is an obscure bug-fixing task for old kernel versions that shouldn't be used unless you know what you're doing.

Accepts

  • .dude: agent name or null for all agents.

  • .ship: old-style outgoing subscriptions to the specified ship or null for all ships.

Example

Filter Gall debug prints

A poke with a mark of %helm-gall-sift will filter Gall verbosity to the specified agents. Note this overrides previous filters and simply removes all filters if the list of agents is empty.

Accepts

Example

Set Gall verbosity flags

A poke with a mark of %helm-gall-verb will enable the specified Gall verbosity flags.

Accepts

  • .veb: currently, the only $verb:gall is %odd.

Example

Kill incoming subscriptions in Gall

A poke with a mark of %helm-gall-lave will kill the specified incoming Gall subscription(s). This is for developer debugging and should not be used unless you know what you're doing.

Accepts

  • .dry: if true, no-op.

  • .subs: a list of tuples where:

    • .v: the %a option simultaneously sends the subscriber a %kick and calls the target agent's +on-leave arm as though the subscriber initiated it. The %g option just calls +on-leave without sending a %kick to the subscriber.

    • .ship: the subscriber's ship.

    • .dude: the agent, a @tas.

    • .duct: the subscription $duct.

Example

Print a hi

A poke with a mark of %helm-hi will print the source of the poke and the incoming message (or its hash and size if it's very large). Note this is the handler for incoming |his. To send outgoing ones, see %helm-send-hi.

Accepts

  • .mes: a $cord message to print or just an atom if it's longer than 100 bytes and you just want the size and hash rather than the message itself for testing.

Example

Pass notes to vanes

A poke with a mark of %helm-pans will pass the given list of $note-arvos to their respective vanes. This is like |pass but for multiple tasks.

Accepts

Example

Run a memory report

A poke with a mark of %helm-mass will tell the runtime to print a memory report.

Accepts

Example

Meld memory

A poke with a mark of %helm-meld will tell the runtime to deduplicate the ship's state, reducing memory usage. Note this can be memory-intensive for ships with large states.

Accepts

Example

Register new moon

A poke with a mark of %helm-moon will save the given moon's pubkey in Jael so it can be booted and communicate on the network. Note that the keys must be provided explicitly.

Accepts

  • .sed: if null, no-op. Otherwise add the given moon with the given pubkey and life in the $udiff:point:jael to Jael. See the |moon generator's source for details of key generation.

Breach a moon

A poke with a %helm-moon-breach mark will breach the specified moon (assuming its a child of your ship), incrementing its $rift.

Accepts

Example

Pack memory

A poke with a mark of %helm-pack will tell the runtime to compact memory.

Accepts

Example

Pass a note to a vane

A poke with a mark of %helm-pass will pass the given $note-arvo to its target vane.

Accepts

Example

Rekey ship

A poke with the mark of %helm-rekey will rotate the ship's networking keys with the given private key. Note this can be dangerous if you provide an incorrect key/life.

Accepts

  • .des: this is a $feed:jael +jam'd and encoded in a $cord with @uw syntax.

Send a hi

A poke with a mark of %helm-send-hi will send a |hi to the target ship with an optional message.

Accepts

  • .her: the target ship.

  • .mes: a message to print on the target ship. Leave the string empty if you don't want a message.

Example

Negotiate migration to directed messaging with a ship

A poke with a mark of %helm-send-ahoy will request to migrate networking with the given ship to Mesa (directed messaging).

Accepts

  • .her: the target ship.

  • .test: if true, it will merely test directed messaging upgrade negotiations but won't actually enable it.

Migrate to directed messaging

A poke with a mark of %helm-mass-mate will migrate networking with the target ship or all ships to Mesa (directed messaging). This is like %helm-send-ahoy except it doesn't do the negotiation part and it can do it for everyone, not just a single ship. This is dangerous and should not be touched unless you know exactly what you're doing.

Accepts

  • .ship: either a specific ship, or null for all ships.

  • .dry: if true, it does a test-run without actually applying the upgrade.

Negotiate reversal of directed messaging migration with ship

A poke with a mark of %helm-send-rege will send a request to the target ship to negotiate a reversal back to old-style Ames networking from directed messaging. This is the inverse of %helm-send-ahoy.

Accepts

  • .her: the target ship.

  • .test: if true, it does a dry-run of the negotiation without actually applying it.

Reverse directed messaging migration

A poke with a mark of %helm-mass-rege will reverse directed messaging migration back to ordinary Ames networking for either a specific ship or all ships. This is the same as %helm-send-rege except it doesn't do the negotiation part and it can do it for everyone, not just a single ship.

Accepts

  • .ship: the target ship, or all ships if null.

  • .dry: if true, it does a dry-run test of the reveral without actually applying it.

Serve a generator over HTTP

A poke with a mark of %helm-serve will bind a generator to a URL path in Eyre so it can be run over HTTP. Note the generator has to be structured like so:

Accepts

  • .binding: a pair of optional site and URL path. Normally the site is empty, so it's like [site=~ path=/foo/bar/baz].

  • .generator is a +trel of:

    • .desk: the desk that contains the generator.

    • .path: the path to the generator, like /gen/foo/hoon.

    • .args: any extra arguments to give the generator.

Example

In the Dojo:

The in the Unix terminal:

Trim memory

A poke with a mark of %helm-trim will request vanes trim their state size at the specified priority level.

Accepts

  • .pri: the larger the number, the lower the priority. Currently vanes don't consider the priority so it doesn't matter what you specify. This might change in the future.

Example

Toggle move trace verbosity

A poke with a mark of %helm-verb will toggle move trace verbosity.

Accepts

Example

Encrypt and write atom to Clay

A poke with a mark of %helm-write-sec-atom will encrypt the given atom and write it to Clay. This is use internally by OAuth machinery and is not generally useful.

Accepts

Configure domain

A poke with a mark of %helm-dns-config will configure an arvo.network (or other) subdomain for the ship. The HTTP server must be bound on port 80 and be publicly available.

Accepts

  • .addr: either the ship's public IP address, or a the URL of a "what is my IP?" reflector that returns the IP in the body of the response (e.g. icanhazip.com) for automatic IP address discovery.

  • .collect: the ship and agent that will handle the request and create the DNS entry. This is typically [~deg %dns-collector].

  • .self-check: whether to perform self-checks or skip them.

  • .reset: whether to clear existing domain & SSL certificate configurations before creating the new one.

Kiln

Helm controls app update synchronization and provides an interface for various filesystem-related system calls.

Approve merge

A poke with a mark of %kiln-approve-merge will approve or reject the specified pending merge.

Accepts

  • .syd: local $desk.

  • .her: foreign $ship.

  • .sud: foreign $desk.

  • .approve: whether to approve or reject the pending merge.

Enable autocommit

A poke with the mark of %kiln-autocommit will enable autocommits for the given mount point. Note this can quickly blow up your ship's state and isn't recommended.

Accepts

  • .mon: a Clay mountpoint as a @tas. Typically this is just the desk name but theoretically things can be mounted with different names.

  • .auto: if false it just does a single commit and isn't actually "auto". If true it auto-commits every 1 second.

Example

Cancel autocommit

A poke with a mark of %kiln-cancel-autocommit will turn off the previously enabled Clay autocommit.

Accepts

Example

Force kernel upgrade

A poke with a mark of %kiln-bump will force a pending kernel upgrade, suspending any incompatible desks.

Accepts

Example

Commit

A poke with a mark of %kiln-commit will commit the given mount point.

Accepts

  • .mon: a Clay mountpoint as a @tas. Typically this is just the desk name but theoretically things can be mounted with different names.

  • .auto: if false it just does a single commit and isn't actually "auto". If true it auto-commits every 1 second.

Example

Sync automerge

A poke with a mark of %kiln-sync-automerge will enable or disable automatic merges for the given sync.

Accepts

  • .syd: local $desk.

  • .her: foreign $ship.

  • .sud: foreign $desk.

  • .auto: is null, defer to global automerge settings. Otherwise, enable if true and disable if false.

Example

Octopus merge

A poke with a mark of %kiln-fuse will perform an octopus merge of the foreign sources into the local desk with the given merge strategies. The sources can also be tracked rather than a one-off merge.

Accepts

  • .syd: the local desk.

  • Then either ~ to clear an existing fuse, or a tuple of:

    • .overwrite: whether to force overwrite any previous fuse.

    • .bas: the base source, a [who=ship des=desk ver=$@(%trak case)]. If ver is %trak it tracks the source rather than just merging a single case.

    • .con: additional sources and their respective merge strategies.

Print octopus merge details

A poke with a mark of %kiln-fuse-list will list the details of any fuses into the given local desk or all desks.

Accepts

  • .k: a (unit desk). If it's null it's for all desks, otherwise the specified one.

Example

Clear inbound blocked moves in Gall

A poke with a mark of %kiln-gall-sear will clear the queue of blocked incoming moves from the given ship.

Accepts

Example

Write to Clay (%info)

A poke with a mark of %kiln-info will write the given $toro:clay and print the specified message to the Dojo.

Accepts

  • .mez: a message to print to the Dojo.

  • .tor: a Clay diff or if it's null, it just prints .mez and does nothing.

Install app

A poke with a mark of %kiln-install will install the given desk on the given remote ship to the given local desk.

Accepts

  • .loc: the local desk.

  • .her: the remote ship.

  • .rem: the remote desk.

Example

Set the kids desk for a sync

A poke with a mark of %kiln-kids will set (or unset) the kids desk for a sync.

Accepts

  • .hos is a trel where:

    • .syd is the local desk.

    • .her is the foreign ship.

    • .sud is the foreign desk.

  • .nex: the kids desk or null to unset.

Example

Add a label to a desk revision

A poke with a mark of %kiln-label will add a label to the specified revision or latest if null.

Accepts

  • .syd: the desk.

  • .lab: the label to apply.

  • .aey: the revision number or null for latest.

Example

Clay merge

A poke with a mark of %kiln-merge will perform the given merge in Clay.

Accepts

  • .syd: the local desk.

  • .ali: the ship to merge from.

  • .sud: the desk to merge from.

  • .cas: the $case to merge from.

  • .gim: the merge strategy.

Example

Mount a desk

A poke with a mark of %kiln-mount will mount the given path to the given mount point.

Accepts

  • .pax: a full path-encoded $beam to a desk, subdirectory or file.

  • .pot: the name of the mount point (typically just the desk name for a desk but it's up to you).

Example

Receive a sync source change request

The %kiln-jump-ask marked poke handler is for publishers to request you change your update source for their app.

Accepts

  • .old: the ship and desk of the old sync source.

  • .new: the ship and desk of the new sync source.

Accept or reject a sync source change request

A poke with a mark of %kiln-jump-opt lets you accept or reject a sync source change request from a publisher.

Accepts

  • .old: old sync source ship and desk.

  • .new: new sync source ship and desk.

  • .yea: change to the new source if true, keep the old source if false.

Propose app subscribers change to a new sync source

A poke with a mark of %kiln-jump-propose will ask all desk subscribers to change their update source to a new ship and desk. This is intended for app publishers if the need to migrate their app distribution to a new ship or desk.

Accepts

  • .syd: the local desk whose subscribers should change their update source.

  • .her: the new ship to sync from.

  • .sud: the new desk on that ship to sync from.

Example

Erase app state

A poke with a mark of %kiln-nuke will disable and erase the state of an agent or all agents on a desk. Note the erased state cannot be recovered and this might break things so be careful.

Accepts

  • .term: either a Gall agent or a desk name.

  • .desk: whether .term is a desk, in which all agents on that desk should be nuked, or whether it specifies just a single agent.

Example

Disable updates for a desk

A poke with a mark of %kiln-pause will disable updates for the specified desk. Note to re-enable them you'll have to re-run the |install generator or equivalent, specifying the ship and desk.

Accepts

Example

Make files public or private

A poke with a mark of %kiln-permission will set permissions for the given path in the given desk to public or private.

Accepts

  • .syd: the desk in question.

  • .pax: the path on that desk you want to make public or private (/ for the whole desk).

  • .pub: whether it should be public of private.

Example

Unsuspend an app

A poke with a mark of %kiln-revive will unsuspend the specified desk if possible.

Accepts

Example

Start/stop agents on a desk

A poke with a mark of %kiln-rein will set which agents should be running or stopped on the specified desk. Note this will reset previous overrides to the desk's running agent list.

Accepts

  • .desk: the desk in question.

  • .rein: a (map dude:gall ?) where the ? says whether each agent should be running or suspended.

Example

Delete files

A poke with a mark of %kiln-rm will delete the files at a given path in Clay.

Accepts

  • .a: a full path-encoded $beam into Clay.

Example

Set global automerge policy

A poke with a mark of %kiln-global-automerge sets whether desks should automatically merge updates, by default.

Accepts

  • .auto: whether desks should automatically merge updates by default.

Example

Add an entry to a schedule file

A poke with a mark of %kiln-schedule will write the given cord to a %sched file in Clay at the given time.

Accepts

  • .where: a path-encoded $beam to a .sched file or a directory within which a .sched file should be created.

  • .tym: the time of the entry.

  • .eve: the event.

Suspend a desk

A poke with a mark of %kiln-suspend will suspend the specified desk.

Accepts

Example

Suspend desks

A poke with a mark of %kiln-suspend-many will suspend the list of specified desks.

Accepts

Example

Sync desk from remote source

A poke with a mark of %kiln-sync will turn on automatic updates for the given desk from the given source.

Accepts

  • .syd: the local desk.

  • .her: the remote ship.

  • .sud: the remote desk.

Example

List existing desk syncs

A poke with a mark of %kiln-syncs will list the currently enabled desk syncs.

Accepts

Example

Uninstall an app

A poke with a mark of %kiln-uninstall will suspend the given desk and disable updates.

Accepts

Example

Unmount a desk

A poke with a mark of %kiln-unmount will unmount the specified desk or mountpoint.

Accepts

Either a simple $term or a path-encoded $beam.

Example

Unsync desk from remote source

A poke with a mark of %kiln-unsync will unsync the given desk from the given remote (or local) source.

Accepts

  • .syd: the local desk.

  • .her: the remote ship.

  • .sud: the remote desk.

Example

Mark/unmark desk as essential

A poke with a mark of %kiln-essential-desk will mark the given desk as essential or not.

Accepts

  • .desk: the desk in question.

  • .ese: whether or not the desk is essential.

Types

These are the types defined in /sur/hood.hoon.

$pike

Desk state.

Source

  • .sync: whether the desk is currently syncing from a remote source.

  • .hash: %cz hash of desk's current revision.

  • .zest: whether it's running, suspended, or suspended pending a kernel-compatible update.

  • .wic: the kernel versions it's compatible with.

$pikes

State of all desks.

Source

$jump

An update to the state of requests to change sync sources.

Source

  • %all: current pending requests.

  • %add: new request.

  • %yea: request approved.

  • %nay: request denied.

$rung

A reference to an upstream commit

Source

$sync-record

Source and destination of a sync in Kiln.

Source

  • .syd: local desk.

  • .her: remote ship.

  • .sud: remote desk.

$sync-state

The state of a sync in Kiln.

Source

  • .nun: nonce.

  • .kid: whether it has a kid desk to merge into.

  • .let: next revision (awaited).

  • .nit: automerge or global default if null.

  • .hav: whether an update is available.

  • .yea: whether the update has been approved.

$sync-update

An update about a sync.

Source

PreviousBaseNextThreads

Last updated