Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

System GClasses

Core runtime, file-system watcher, pseudo-terminal, OTA updates, and miscellaneous system services.

Source: kernel/c/root-linux/src/c_yuno.c, c_fs.c, c_pty.c, c_ota.c, c_gss_udp_s.c


C_YUNO

Main yuno GClass — the root grandmother of every yuno application. Manages services, configuration, logging, tracing, IP filtering, and system-wide commands.

PropertyValue
StatesST_STOPPED, ST_IDLE

Stats

What stats-yuno answers for __yuno__, and what a watch-yuno-stats pushes as its cpu kind, read once a second (timeout_stats):

StatMeaning
cpuPercent of one core the process used.
publicationsHow many publish-stats the yuno is sending (see below). Since 7.28.11.
uptime, start_dateSeconds since the yuno started, and when.
mem_rss_kbResident memory of the process, KB (VmRSS).
mem_node_total_mb, mem_node_available_percentMemory of the node, and the percent of it still available (MemAvailable). A ramdisk takes its size from here.
disk_size_in_gigas, disk_free_percentSize and free percent of /yuneta.
disk_min_free_percent, disk_min_free_path, disk_min_free_size_gigasThe FULLEST filesystem the yuno writes to: /yuneta and the store of each of its C_TRANGERs (a queue on a ramdisk, a store on another disk). Its free percent, a path of the yuno on it, its size. Since 7.28.4.

The filesystems are looked for once a minute (a yuno can have thousands of stores, on a handful of devices), and each is measured at every reading. Before 7.28.4 a yuno told only of /yuneta: the queues of a simulator filled a ramdisk (/mnt/ramdisk) while /yuneta had room, and each simulator died on a message it failed to save. Example, from stats-yuno:

{"cpu": 12, "uptime": 86400, "mem_rss_kb": 5324,
 "mem_node_total_mb": 31885, "mem_node_available_percent": 35,
 "disk_size_in_gigas": 1832, "disk_free_percent": 73,
 "disk_min_free_percent": 4, "disk_min_free_path": "/mnt/ramdisk/queues",
 "disk_min_free_size_gigas": 26}

Test: tests/c/c_yuno_stats.

Publishing its stats (publish-stats)

Since 7.28.11 a yuno can SEND the stats of one of its services to whoever asks, every period, from its own periodic timer, instead of being asked for them again and again. It is what the agent’s watch-yuno-stats asks of its yunos.

# the yuno's own stats (the `cpu` reading of a watch), every 2 s, for 60 s
publish-stats stats_service=__yuno__ period=2000 ttl=60000
# a service's stats; no ttl: the attribute publish_stats_ttl (60000 ms)
publish-stats stats_service=db_events period=5000
# never ending on its own: until stop=1 or the requester goes
publish-stats stats_service=__yuno__ period=2000 ttl=-1
publish-stats stats_service=__yuno__ stop=1

Each publication is the answer of a stats request (EV_MT_STATS_ANSWER, the stats in data), sent with the routing of the publish-stats request reversed, so it reaches the requester the way its own answers do, with whatever it put in __md_iev__. One publication per requester and service: a new call replaces it and renews it. It ends -- with an INFO “publish-stats ended” and its reason -- when its ttl passes without a new call (0 or -1: never), when the requester is no more, when the requester’s link (a C_IEVENT_CLI) leaves its session, when the service is gone, or when the service is itself a link (a C_IEVENT_CLI or C_IEVENT_SRV) out of its session, which otherwise answers every period with -1 “not in session” and a WARNING. stop=1 ends it at once. The requester must be a service (it is found again by name at each publication). period is never under timeout_periodic, and a yuno keeps at most 64 publications. Refused: a service that does not exist (“Service not found”), a requester that is not a service, a stats_service longer than NAME_MAX (no service is named so, and the answer is “stats_service too long”, with stop=1 too).

ParameterMeaning
stats_serviceThe service whose stats are sent: __yuno__ for the yuno’s own, empty for the default service.
statsWhich stats, as in a stats request (empty: all).
periodMilliseconds between two (default 2000).
ttlMilliseconds it lives unless asked again. 0 or -1: no automatic end. Absent: the attribute publish_stats_ttl (60000, writable).
stopEnd this requester’s publication of that service.

Test: tests/c/c_yuno_publish_stats.

Commands (selection)

CommandDescription
view-gclass-registerList all registered GClasses.
view-services / view-top-servicesList services.
view-gobj / view-gobj-treeInspect the gobj tree.
enable-gobj / disable-gobjEnable or disable a gobj.
write-attr / view-attrs / attrs-schemaRead/write gobj attributes. write-attr gobj_name=<g> attribute=<a> value=<text>: the value is TEXT, read as the type of the attribute exactly as the parser reads a parameter of that type (command_parameter_from_text()): a boolean as true/false, yes/no, on/off or an integer, an integer or a real of the JSON grammar with nothing before or after it and in its range (value=007, +5 and .5 are refused since 7.27.0), a dict or a list as its json (value={"a":1}, value=[1,2]), a json as its json or else the text itself (value=word is the string "word"). A text that does not read as one is refused and nothing is written: -1 “<gobj>: attr ‘debug’ takes a boolean (true/false, yes/no, on/off, or an integer), not a text that does not read as one”. No refusal of write-attr repeats the value, because it can be a secret’s. A value with blanks is written quoted (value='correct horse battery'): unquoted, the words after the first are extra text, which the command parser refuses, and it does not repeat them when the line carries a secret (attribute=password value=correct horse battery answers “... extra parameters: ‘<...>’”. Up to 7.26.9, it answered 'horse battery'), see command_mask_secret_line(). A pointer attr is refused (“is a pointer: no command writes it”). Before 7.27.0, atoi() and strtoll() wrote value=yes as FALSE, abc as 0 and 12abc as 12. A json attr refused a bare word and echoed the value it refused, a secret’s too. A dict or a list answered “Can’t write attr”.
set-global-trace / set-gclass-trace / set-gobj-traceConfigure trace levels. level is the name of a level (or its bitmask in digits). set takes 1/true/set/yes/on to set and 0/false/reset/no/off to reset, as text (a number written as a JSON integer: set=+1 and set=01 are refused) or as json: command-yuno id=<id> service=__yuno__ command=set-gclass-trace gclass=C_TCP level=traffic set=1, or {"gclass": "C_TCP", "level": "traffic", "set": true} from a GUI. Anything else answers -1 “<role^name>: bitmask set or re-set?” (since 7.27.0: it was read as text by atoi(), so set=yes was a RESET, and a GUI’s set: 1 was refused as no text). The same set in set-global-no-trace, set-gclass-no-trace, set-gobj-no-trace and set-trace-filter.
reset-all-traces / set-deep-traceTrace management. The set of set-deep-trace and set-machine-format is a number, the level or the format (set / true are 1, reset / false are 0).
info-global-traceShow trace configuration.
view-configShow yuno configuration.
info-memMemory usage info.
publish-statsSend the stats of a service to the requester every period, see above.
info-cpus / info-ifs / info-osSystem information. info-ifs gives each interface its mac, and up / running / loopback (7.31.21+). info-os adds os, the distribution (get_os_info()).
info-machineThe machine at once (7.31.21+): os, cpu (model, logical_cpus), memory (total, available, swap_total, swap_free), disks (each block device at the first place it is mounted: device, mountpoint, fstype, size, used, available, use_percent, with squashfs left out), ifs (as info-ifs) and uptime (seconds, boot_date). Sizes in bytes. A part that cannot be read is null, and logged. If the hostname or the node_uuid is not UTF-8, the answer is -1 with an ERROR (up to 7.31.29 it was 0 with no data and no log). Of a node, through its control center: command-agent agent_id=<node> agent_service=__yuno__ cmd2agent=info-machine.
info-uptimeUptime and boot date of the machine, and uptime and start date of this yuno.
info-inotifyinotify limits (/proc/sys/fs/inotify/*) plus this yuno’s own usage (instances + watches).
list-allowed-ips / add-allowed-ipIP access control.
truncate-log-fileTruncate the log file.
view-log-countersShow log event counters.
add-log-handler / del-log-handler / list-log-handlersLog handler management.
shutdownStop this yuno, orderly.

Open files

limit_open_files (default 0) is the soft limit of open files the yuno asks for at its start. With 0 it raises its soft limit to its hard one: a yuno started from a desktop session gets the soft 1024 of systemd --user, and a timeranger2 follower holds a descriptor per key directory of each feed (FS_FLAG_DIR_FDS), so 1024 ran out (up to 7.25.21, 0 left the limit as it came). A positive value sets both limits to it when the soft one is lower. What it got is in limit_open_files_done.

{
    "yuno": {
        "limit_open_files": 200000
    }
}

Uptime

The uptime stat is the yuno’s: seconds since its mt_create, on the monotonic clock (a change of the wall clock does not move it). The machine’s is answered by info-uptime, from CLOCK_BOOTTIME (which, like /proc/uptime, counts the time the machine was suspended), with the boot time it gives:

ycommand -c 'command-yuno id=<id> service=__yuno__ command=info-uptime'
# "data": {"machine_uptime": 3142, "machine_boot_time": 1790924758,
#          "machine_boot_date": "2026-10-02T09:05:58.0+0200",
#          "yuno_uptime": 2803, "yuno_start_time": 1790925097,
#          "yuno_start_date": "2026-10-02T09:11:37.123456789+0200"}

Up to 7.25.21 the uptime stat was the machine’s uptime in jiffies (/proc/uptime × HZ), under a description that said it was the yuno’s.

See also the Yuno API for C helper functions.


C_FS

File-system watcher — monitors directory changes using the fs_watcher engine.

PropertyValue
StatesST_IDLE
Output eventsEV_FS_CHANGED, EV_FS_RENAMED, both with {"path", "filename"}

Key attributes

AttributeTypeDescription
pathstringDirectory to watch.
recursivebool1: watch the whole tree under path, the subdirectories created later included. 0 (default): only the entries of path itself.
infoboolLog the watched directory on startup.
subscriberpointerWho gets its events. Default: its parent (the CHILD subscription model).
size_dl_watchint (stats)1 while the path is watched, 0 if not. One watcher, whether recursive or not (the name is older than that).

A watch that cannot be armed fails the start of C_FS (logged), and a watch whose read fails later (FS_WATCHER_GONE_TYPE) is logged and gone: size_dl_watch reads 0, and nothing more is published.

What it publishes

One event per change the watcher reports, path being the directory and filename the entry that changed:

Change (fs_watcher type)Event
directory created / deleted (FS_SUBDIR_CREATED_TYPE, FS_SUBDIR_DELETED_TYPE)EV_FS_CHANGED
file created / deleted / modified (FS_FILE_CREATED_TYPE, FS_FILE_DELETED_TYPE, FS_FILE_MODIFIED_TYPE)EV_FS_CHANGED
rename (FS_FILE_RENAME_TYPE, not reported by the watcher today)EV_FS_RENAMED
events lost (FS_OVERFLOW_TYPE)EV_FS_CHANGED once, for the watched root (filename empty). The rescan pass that follows publishes nothing

A host creates it as its child and declares both events in its FSM: a C_FS subscribes its parent (or the gobj in subscriber) by itself, the CHILD subscription model:

priv->gobj_fs = gobj_create("", C_FS, json_pack("{s:s, s:b}",
    "path", "/yuneta/development/docs",
    "recursive", 1
), gobj);
gobj_start(priv->gobj_fs);

Up to 7.25.20 it subscribed nobody, and every host subscribed by hand (gobj_subscribe_event(priv->gobj_fs, NULL, 0, gobj)). A host that still does subscribes twice, and the second subscription replaces the first with a warning (“subscription(s) REPEATED, will be deleted and override”): drop the call.

Up to 7.25.20 the types were read as bits: a deleted directory published nothing (and leaked the kw built for it), and the other changes were published only because the value of “file modified” (5) shared bits with theirs.

recursive is one watcher, whichever its value: with 1 it recurses by itself (FS_FLAG_RECURSIVE_PATHS). Up to 7.25.20 a recursive C_FS also added a recursive watcher for each subdirectory it found at start, each with its own inotify fd, so a change N levels down was published N+1 times (a file created in a/b/ three times). Also, every watcher recursed, so recursive: 0 reported the subdirectories too. With "recursive", 0:

priv->gobj_fs = gobj_create("", C_FS, json_pack("{s:s, s:b}",
    "path", "/yuneta/development/docs",
    "recursive", 0      // docs/x.md is published, docs/api/y.md is not
), gobj);

C_PTY

Pseudo-terminal — spawns a shell or process in a PTY and provides bidirectional I/O.

PropertyValue
StatesST_IDLE, ST_WAIT_STOPPED, ST_STOPPED
Input eventsEV_WRITE_TTY ({"gbuffer": <the bytes to type>})
Output eventsEV_TTY_OPEN, EV_TTY_DATA (content64: what the terminal printed, base64), EV_TTY_CLOSE, EV_STOPPED (when it is not volatile)

Key attributes

AttributeTypeDescription
processstringCommand to execute (default bash), no arguments.
rowsintegerTerminal rows.
colsintegerTerminal columns.
cwdstringWorking directory.
max_tx_queueintegerMaximum transmit queue size.
rx_pausedbooleanFlow control of the host (writable, default FALSE).

Flow control: rx_paused

C_PTY reads its terminal as fast as the process writes, and publishes each read as an EV_TTY_DATA. A host that sends that output on (the agent sends it to the sessions of a console) can stop the reading while it has too much to send, with the same contract as C_TCP’s rx_paused:

gobj_write_bool_attr(pty, "rx_paused", TRUE);   // the output has nowhere to go now
...
gobj_write_bool_attr(pty, "rx_paused", FALSE);  // it drained: read again

Up to 7.30.26 there was no way to stop the reading, and a host that was not able to send the output on as fast had to keep it all. A C_PTY that is not volatile published EV_STOPPED at its stop without declaring it (an ERROR “event NOT in output event list”). Test: tests/c/c_pty_flow_control.

process is remote-settable (the agent’s authz-gated open-console command), so since 7.6.0 it is resolved against a fixed trusted-dir allowlist, never the inherited $PATH: an absolute path is accepted only if executable, a bare name is resolved against /bin, /usr/bin, /sbin, /usr/sbin, /usr/local/bin (in order), a relative-with-slash name is rejected, and anything else fails closed (no exec). The spawn uses execv, not execvp, so a planted $PATH entry cannot hijack a bare process name.


C_OTA

Over-the-air update manager — downloads and applies firmware updates.

PropertyValue
StatesST_STOPPED, ST_IDLE, ST_WAIT_RESPONSE

Key attributes

AttributeTypeDescription
url_otastringOTA server URL.
cert_pemstringTLS certificate (PEM).
ota_statestringCurrent OTA state (read-only).
forceboolForce update even if role differs.
timeout_validateintegerValidation timeout in seconds.

Commands

CommandDescription
download-firmwareStart firmware download.

C_GSS_UDP_S

Gossamer UDP server — manages multiple virtual channels over a single UDP socket. It is what logcenter listens with: a C_UDP_S child, one CHANNEL per peer, and the frames of each channel joined until a NUL (the log handler of a yuno sends a log line longer than one datagram in pieces, the NUL after the last one).

PropertyValue
StatesST_IDLE
Input eventsEV_SEND_MESSAGE (a gbuffer to send: to its address, or, with none, to the known peer its label names -- see Answer a peer), and from its C_UDP_S: EV_RX_DATA, EV_TX_READY, EV_STOPPED. Also EV_TIMEOUT_PERIODIC from its timer, and EV_TIMEOUT from its restart timer
Output eventsEV_ON_OPEN (a new channel), EV_ON_MESSAGE (a whole frame, its gbuffer in the kw, without the NUL, and the gbuffer carries its peer as label and address), EV_ON_CLOSE (a channel with no datagram for seconds_inactivity)

A channel is keyed by the PEER of the datagram, the label C_UDP_S writes in the gbuffer ("ip:port"). So the pieces of the frames of two peers never mix, however they interleave:

peer A "a1"   peer B "b1"   peer A "a2\0"   peer B "b2\0"
-> EV_ON_OPEN, EV_ON_OPEN, EV_ON_MESSAGE "a1a2", EV_ON_MESSAGE "b1b2"

Up to 7.25.4 C_UDP_S wrote that label only when tracing, every peer was the channel "", and the same datagrams came out as "a1b1a2" and "b2" -- on logcenter, corrupt log records whenever two yunos sent long lines at the same time. tests/c/c_udp_s_rx.

json_t *kw_gss = json_pack("{s:s, s:I}",
    "url", "udp://127.0.0.1:1992",
    "seconds_inactivity", (json_int_t)300
);
hgobj gss = gobj_create("logs", C_GSS_UDP_S, kw_gss, gobj);    // gobj hears EV_ON_*

exitOnError (default true) is passed to its C_UDP_S: a listen that fails, at the start or at a restart, exits the yuno with code 0 (logcenter: hearing the logs is its role). A yuno for which the UDP listener is secondary sets it false, and the C_UDP_S degrades instead (see C_UDP_S, A listen that fails):

json_t *kw_gss = json_pack("{s:s, s:b}",
    "url", "udp://127.0.0.1:1992",
    "exitOnError", 0        // the yuno goes on without its UDP listener
);

Answer a peer

The gbuffer of an EV_ON_MESSAGE carries its peer twice: as its LABEL (gbuffer_getlabel(), "ip:port", the name of its channel) and as its ADDRESS (gbuffer_getaddr()). EV_SEND_MESSAGE takes either:

PRIVATE int ac_on_message(hgobj gobj, gobj_event_t event, json_t *kw, hgobj src)
{
    gbuffer_t *frame = (gbuffer_t *)(uintptr_t)kw_get_int(gobj, kw, "gbuffer", 0, 0);

    gbuffer_t *answer = gbuffer_create(64, 64);
    gbuffer_append_string(answer, "ack");
    gbuffer_setlabel(answer, gbuffer_getlabel(frame));  // or gbuffer_setaddr() with its address
    gobj_send_event(gss, EV_SEND_MESSAGE,
        json_pack("{s:I}", "gbuffer", (json_int_t)(uintptr_t)answer),   // the kw owns it
        gobj
    );

    KW_DECREF(kw)
    return 0;
}

Up to 7.25.4 a frame carried neither its peer’s label nor its address, so no host was able to answer the peer of a frame. Also, EV_SEND_MESSAGE looked the channel up by the label and did not use it: a send by address (the documented way) logged “UDP channel NOT FOUND” for every datagram, and a send by label had no address: the kernel refused the datagram (EINVAL), and C_UDP_S took that for a disconnection and stopped, reading too. The label contract is the original one (the pre-v7 C_UDP_S sent to the "ip:port" of the label). The address is how C_UDP_S sends since v7. tests/c/c_udp_s_rx, case 5.

When its C_UDP_S stops by itself

C_UDP_S stops by itself when its read fails or cannot be started again (no memory for the next read, a socket error): it logs the cause as an ERROR and publishes EV_STOPPED -- while it still RUNS, which is how C_GSS_UDP_S tells it from a stop made from outside. C_GSS_UDP_S then:

A send is refused whenever the C_UDP_S is not in ST_IDLE: stopped, or still stopping (ST_WAIT_STOPPED, while a send of its own is in flight, the window before its EV_STOPPED). The event answers -1, and ONE warning is logged per stop, “EV_SEND_MESSAGE while the UDP server is stopped, dropped”, with udp_state. The count comes with the restart, or, if the C_GSS_UDP_S is stopped first, with its stop (“UDP server stops with sends refused while it was stopped”, tx_dropped). After a restart whose listen failed (exitOnError false), the sends are refused until the C_UDP_S listens by itself, and the count comes with the first send it takes then:

{"msg": "EV_SEND_MESSAGE while the UDP server is stopped, dropped", "udp_state": "ST_STOPPED"}
{"msg": "yev_create_accept_event() FAILED"}
{"msg": "Listening again after a failed listen"}
{"msg": "UDP server listening again, sends refused while it was not",
 "url": "udp://127.0.0.1:24296", "tx_dropped": 2}

Up to 7.30.19 that count was said by nobody: it went into the count of the next restart or stop, and the next refused send wrote no warning.

A C_UDP_S stopped from OUTSIDE (a gobj_stop() of it alone: it no longer runs when its EV_STOPPED comes) is not started again -- that stop was somebody’s decision. It is said once, INFO, “UDP server stopped from outside, it is not started again”, and the sends are refused as above.

Its own stop (gobj_stop() of the C_GSS_UDP_S) stops the C_UDP_S too, and that EV_STOPPED is its end, not a restart. A start that comes while that stop still waits (a stop and a start in the same turn, the read of the C_UDP_S still being canceled) starts the C_UDP_S when its EV_STOPPED comes, on the next cycle of the loop (EV_START_UDP_SERVER). Otherwise, a start at once finds it still holding its socket.

If it is used, a timeout_base of 0 or less arms no timer at all: no peer forgotten after seconds_inactivity, and no base for the backoff. It is refused at the create with a WARNING (“timeout_base <= 0 would arm no timer ...”), and the default 5000 is used (and written back to the attribute):

json_t *kw_gss = json_pack("{s:s, s:i}",
    "url", "udp://127.0.0.1:1992",
    "timeout_base", 2000        // inactivity check, and first restart delay
);
hgobj gss = gobj_create("logs", C_GSS_UDP_S, kw_gss, gobj);

Up to 7.25.20 the EV_STOPPED was taken with no action: the service was not able to receive again, and every send reached a stopped C_UDP_S and logged “Event NOT DEFINED in state”. tests/c/c_gss_udp_s_self_stop.

Key attributes

AttributeTypeDescription
urlstringUDP listening URL.
timeout_baseintegerPeriod of the inactivity check, and first delay of a restart of the C_UDP_S, in milliseconds (default 5000, and <= 0 is refused with a warning and the default used).
seconds_inactivityintegerSeconds without a datagram before a channel is closed (default 300).
disable_end_of_frameboolPublish every datagram as it comes (EV_ON_MESSAGE with the EV_RX_DATA kw), without joining until a NUL.
max_channelsintegerPeers held at once (default 1024, 0 no limit). A datagram of a new peer beyond it is dropped.
max_frame_sizeintegerBytes of one frame (default 1048576). A frame with no NUL within it is delivered cut at this size.
max_pending_bytesintegerBytes of all the unfinished frames together (default 8388608, 0 no limit). Beyond it the datagram is dropped, with the unfinished frame of its peer.

What a peer can hold

A frame costs this yuno memory before it is a frame, and the peer decides how much: every source port of a host is a peer, and each keeps its unfinished frame for seconds_inactivity. So three caps bound it:

CapWhen it is reachedLogged
max_channelsthe datagrams of a NEW peer are dropped, but the peers held go ononce, “Too many peers, datagrams of new peers dropped”, and again only after a peer has gone
max_frame_sizewhat came is delivered cut, and a new frame begins“Frame without end within max_frame_size, delivered cut”, at most once per 10 s, with the count
max_pending_bytesthe datagram is dropped, with the unfinished frame of its peer“Too many bytes in unfinished frames, ...”, at most once per 10 s, with the count

The buffer of a frame starts at 4 KB and doubles as bytes come, up to max_frame_size. If each peer got a buffer of 1 MB from its first byte, with no cap on the peers, a sender of one-byte datagrams from many source ports can take logcenter to its memory ceiling. (Up to 7.25.4 every peer shared one channel, and the corrupt joins above were the price.) tests/c/c_udp_s_rx, case 4.

The defaults fit logcenter, which creates its C_GSS_UDP_S with only the url: one peer per yuno of the node. A host that expects more peers, or longer frames, passes the caps when it creates it:

json_t *kw_gss = json_pack("{s:s, s:i, s:i}",
    "url", "udp://127.0.0.1:1992",
    "max_channels", 4096,
    "max_pending_bytes", 32*1024*1024
);
hgobj gss = gobj_create("logs", C_GSS_UDP_S, kw_gss, gobj);