Concepts

Use the registry to inspect and change Peios configuration. Start with the current value, look up its meaning, and check the program that consumes it after a change. A successful write alone does not show that the new setting is in use.

Start with a read #

These commands only read settings and documentation:

reg ls Machine/System/KMES -l
reg get Machine/System/KMES BufferCapacity -L
regman 'Machine\System\KMES' BufferCapacity

• reg ls shows the values and their types.
• reg get -L shows the effective value, its winning layer and sequence. It does not list all the entries hidden by that winner.
• regman explains the expected type, default, valid range and when the setting applies. It reads installed documentation, not live state.

If you do not know the path, try regman -k buffer. Find where a setting lives maps common locations. You can also browse with Registry Editor. The editor shows the same manual beside each key and value.

Make one controlled change #

1. Read the setting's regman entry. Check Type, Valid and Applies, including any restart or reboot requirement.
2. Record the old value and winning layer. For recovery that must retain permissions and layer entries, take a backup.
3. Choose the destination layer deliberately. A write needs permission on both the key and the layer; higher-precedence policy can keep a local write from becoming effective.
4. Change the value with its explicit type, then read it back.
5. Check the consuming component's status and events after the documented application point. It may reject the stored value and retain an earlier one.

Change a setting and verify it walks through this sequence. For the desktop controls, use Registry Editor; for all command options, use reg.

Know what you are addressing #

CurrentUser is an alias for the caller's own Users\<SID> key. Paths are case-insensitive; quote backslash paths in a shell or use forward slashes with reg. The value name is a separate argument, not part of the key path. See Keys, values, and types.

If the result is unexpected #

When you need implementation detail #

Applications and tools reach the registry through the kernel's Layered Configuration Subsystem (LCS). Userspace sources persist its data; loregd supplies the default registryd role. You do not edit their backing databases to change a setting.

The source operations guide covers availability and trust. The kernel LCS TRM covers the data model, syscall ABI, watch implementation and source protocol.

A registry command usually takes a key path and a separate value name. Keeping them separate avoids changing the wrong setting:

reg get Machine/System/KMES BufferCapacity
reg ls Machine/System/KMES -l

Keys and values in a command #

Keys contain subkeys and values; values do not contain other values. reg get KEY lists the key's effective values. reg get KEY NAME reads one value. The literal @ in the value-name position addresses the unnamed default value, if the key has one.

A key need not have a default value. A default value is also different from a setting's documented default: a consumer may use a compiled-in default when no registry value is present.

Keys #

Machine\System\KMES names a key. Its permissions cover the values it contains. To give two values different permissions, put them in different keys; there are no per-value permission lists.

Key-name components cannot contain \, / or a null byte. Empty components, doubled separators and trailing separators are invalid.

Values #

A value has a name, a type tag and data. Unlike a key-name component, a value name may contain / or \: it is not a path. The null byte is forbidden; the empty name is reserved for the default value.

The value types #

Use the type the owning component documents in regman. For a command-line write, an explicit prefix avoids unintended type inference:

For example, sz:007 preserves the text 007. Without the prefix, reg infers an integer and loses the leading zeros. See reg value literals for encoding lists, bytes and numbers.

The hardware-resource types are retained for format fidelity and have no Peios-specific meaning. Byte encodings, including Peios UTF-8 strings and link targets, are documented in the LCS value representation.

Typed, but opaque #

The registry does not check whether ordinary value data is sensible for its consumer. A known type tag can accompany malformed data, such as a number with the wrong length. Registry Editor shows such data in red as bytes. Unknown type codes and invalid requests can still be rejected; "opaque" does not mean every write succeeds.

REG_LINK on a link key is the exception: the kernel interprets it to resolve the target. For other settings, follow Change a setting and verify it.

Names, case, and paths #

reg accepts forward slashes and backslashes as path separators. In a shell, use forward slashes or quote a backslash path:

reg get 'Machine\System\KMES' BufferCapacity

Names are case-insensitive and retain their display case. Case matching is locale-independent, but there is no Unicode normalization: visually identical names with different Unicode representations can be distinct.

Volatile keys #

A volatile key is held in memory and disappears on reboot or when its store unloads. Its children must also be volatile. reg info KEY shows whether a key is volatile; Registry Editor also shows this in the key pane.

Volatility is about persistence. It does not tell you when a setting applies. A persistent setting may still require a reboot; check the regman Applies field.

Where to go next #

• Make and verify a change
• Understand which layer wins
• Check key permissions

Start with the setting's purpose and the program that reads it. Search the installed registry manual, find the key, then inspect its live values. A path alone does not tell you whether a value is a setting to change, a fact published by a service, or private to one user.

Search before changing anything #

These commands only read documentation and current state:

regman -k buffer
regman 'Machine\System\KMES' BufferCapacity
reg ls Machine/System/KMES -l
reg get Machine/System/KMES BufferCapacity -L

1. Search installed documentation with regman -k, using a word from the setting's name or purpose.
2. Look up the returned key and value; check type, valid values, default and application timing. A key-only lookup lists its documented values.
3. Inspect live values with reg. -L shows the winning layer and sequence, not every hidden entry.

For graphical browsing, Registry Editor shows the same manual beside live values. regman reads documentation, not live state: a documented entry need not be set. Full command syntax is in regman and reg.

Common locations #

These common locations are backed by pinned source revisions, not an exhaustive schema or a guarantee about your installed release. Check your installed manual before changing a field.

The service and init locations come from peinit's key constants; its init manual explains the global settings. The distinction between shared authentication policy and authd configuration is explicit in its manual. The descriptor editor's catalogue documentation explains the Common example.

Check whose user settings you are reading #

Users\<SID> identifies a principal by SID. authd creates a private user root at authenticated sign-in, with access for that user, SYSTEM and Administrators; it does not reset an existing root's permissions.

CurrentUser is an alias, not a separate hive. For a caller-supplied absolute path, LCS resolves its leading CurrentUser component using the calling thread's effective token. A service or impersonating thread may therefore address a different user's settings from your interactive shell. See the alias's exact rules.

Machine-to-user fallback is consumer-specific. For example, session locale combines machine and user settings for new sessions' environment, under its own precedence rules. Those rules do not apply automatically to other programs.

Separate settings from reported facts #

The registry also contains state written by running components. Under Machine\System\Network:

• Profiles and interface rules are operator configuration.
• netd publishes Status and readiness facts. Its Status keys have SYSTEM-only writes and Everyone reads. Inspect them; use the documented configuration keys to request changes.
• A network's status can include remembered DNS server observations. These differ from both active resolver state and the fallbacks and overrides in resolvd's configuration under Machine\System\Network\Dns.

Use Configuring profiles and Name resolution to make and verify a network change; a stored value alone does not prove active use.

If you cannot find or read it #

• No manual entry: check the owning component's documentation. The installed manual is only as complete as the documentation shipped with it.
• No live value: check the consumer's missing-value behavior. Do not create the key merely because the map or manual mentions it.
• Access denied: check the exact key's permissions. Listing a parent and reading a child are separate operations.

There is no universal Everyone-read rule. The default hive descriptor grants read access to Authenticated Users and full access to SYSTEM and Administrators; individual keys can use different descriptors, including the network Status keys above. Knowing a path does not grant access.

Once you have identified the setting and its consumer, follow Change a setting and verify it for a controlled edit, read-back and consumer verification.

A registry write changes stored configuration. The program that reads it still decides whether it is valid and when to use it. Treat a change as finished only after checking both the stored result and the consumer.

1. Look up the setting #

If you do not know its key, start with Find where a setting lives. Confirm that it is operator configuration rather than a service's reported state.

regman 'Machine\System\KMES' BufferCapacity

Read the expected Type, Default, Valid range and Applies field. In this example, the documented type is REG_QWORD; the value is a power-of-two buffer capacity and applies live. Other settings may apply only on service restart or reboot.

regman reads package documentation, not the live registry. If it has no entry, find the owning component's documentation before changing the value. An undocumented setting is not evidence that any type or value is safe.

2. Inspect and prepare recovery #

reg ls Machine/System/KMES -l
reg get Machine/System/KMES BufferCapacity -L

Record the effective value, type and winning layer. -L shows only the winner, not every shadowed entry. If the setting is absent, record that fact too; writing the documented default is not the same as leaving it unset.

Choose the layer to write into, check permissions, and decide how you will recover. Use a backup when you need the subtree's permissions and layered entries retained. A JSON export is useful for review but is not an equivalent backup.

3. Make the smallest intended change #

For example, after deciding an 8 MiB buffer is appropriate for this machine:

reg set Machine/System/KMES BufferCapacity qword:8388608 --layer base
reg get Machine/System/KMES BufferCapacity -L

The type is explicit and the destination is explicit. A higher-precedence layer can still win, so read-back may show a different value. See Layers before rewriting the setting repeatedly.

For a guarded update, reg set --expected-seq N can reject a concurrent change with exit status 6. The check is against the destination layer's entry: use the sequence from reg get -L only when that winning entry is in the layer you intend to write. If it is not, the effective sequence is not a sequence for your target layer. See reg and the transaction notes.

4. Verify that the consumer accepted it #

1. Confirm the effective value and type with reg or Registry Editor.
2. Follow Applies: allow the live consumer to process the change, or arrange its documented restart or reboot if required.
3. Inspect that component's status and relevant events. A watch notification or a successful reg set is not an acceptance acknowledgement.
4. Test the behavior the setting was intended to change.

Use the event and audit guides for reading records. Do not treat silence in the log alone as proof of acceptance.

If the stored value is rejected #

Consumers validate their configuration. Under reject-or-keep, a rejected setting remains stored while the consumer keeps its last known-good value and logs the rejection. It does not clamp or silently repair the invalid value.

Check the event for the rejected value and the retained value. Correct the type or data according to the component's manual, then repeat both checks. The consumer's documented fallback matters: for example, SdDefaults uses a compiled descriptor when an override is invalid.

Registry settings follow the same check #

LCS reads its own settings under Machine\System\Registry. It validates changes before using them and logs rejections. Deleting one of these values does not necessarily reset the running parameter: the documented LCS behavior is to retain the last active value when a parameter is missing. See Registry startup and configuration.

If the write fails or times out #

A write can fail because of access, input, capacity or source errors. Use the reg exit-status reference to distinguish them. After a timeout or source failure, read the affected state before retrying: a dispatched write or commit may still have succeeded.

Recover deliberately #

• For an isolated edit, restore the intended value in the intended layer and verify the consumer again.
• To withdraw a layer's entry, use per-layer deletion.
• To remove a bundle of configuration, review layer recovery.
• To replace a damaged subtree from a snapshot, follow backup and restore.

Removing configuration does not reverse changes to a key's security descriptor or undo effects already performed by a consumer.

Use a watch to notice that configuration changed. Use a fresh read to learn the current state, and the consuming component's status and events to learn whether it accepted that state.

Watch a key from a terminal #

reg watch Machine/System/KMES --subtree --filter value

This remains running until interrupted. --subtree includes descendant keys; omit it for only the named key. The filters are value, subkey and sd, as a comma-separated list; the default is all three. --count N limits the run to N events. See reg watch.

Arming a watch requires KEY_NOTIFY. Reading values separately requires KEY_QUERY_VALUE; a watch is not permission to read everything beneath it.

Read after a notification #

reg watch reports that something under its filter changed. It does not decode the detailed change records. In another terminal, inspect the current state:

reg get Machine/System/KMES
reg get Machine/System/KMES BufferCapacity -L

Watches describe effective-state changes, not a history of every layer write. A write hidden by another layer need not change the effective answer. Layer operations may require a full re-read rather than provide one notification for every affected value.

A notification is not consumer acceptance #

Uncommitted transaction changes are not published to watchers. A committed change can notify a consumer, but the consumer still has to read, validate and apply it. Follow Change a setting and verify it instead of treating a watch line as confirmation that the service changed.

Recover after missed events #

Watch delivery is best-effort, with bounded queues. An overflow means the record is incomplete; re-read the key and, for a subtree watch, its subtree. Restore, layer deletion and a source re-registration can also trigger this recovery path. A watch is not a backup or a complete change journal.

After a source outage, wait for reads to work again and resynchronise from current values. After restarting reg watch, take a fresh read rather than assume the new stream includes changes made while it was stopped.

When the same path names a different key #

A watch follows the key object opened at registration, not the path text. If another key replaces it at the same path, the old watch does not move to the replacement. Reopen the path and arm a new watch when you need to observe the replacement. Merely hiding a key does not destroy its watch; the object and path distinction is explained in the LCS watch dispatch reference.

Where to go next #

• Access rights for watching and reading
• Source interruptions and safe retry
• LCS watch model, record layout, and queue behavior for client implementers