Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/cloudlinuxos/command-line_tools/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2906,11 +2906,12 @@ cldeploy --hostinglimits # update httpd and install m

**Per-domain commands**

These manage [CloudLinux Isolates](/cloudlinuxos/isolates/#lve-per-domain) — resource limits for an individual website rather than for the whole account. They require a kernel with per-domain LVE support; on a kernel without it every one of them exits with code `38` and the message <span class="notranslate">`Domain limits are not supported by this kernel`</span>.
These manage [CloudLinux Isolates](/cloudlinuxos/isolates/#lve-per-domain) — resource limits for an individual website rather than for the whole account. They require a kernel with per-domain LVE support; on a kernel without it every one of them except <span class="notranslate">`regenerate-domains`</span> exits with code `38` and the message <span class="notranslate">`Domain limits are not supported by this kernel`</span>. On such a kernel <span class="notranslate">`regenerate-domains`</span> changes nothing and still exits successfully, so its exit status does not show whether per-domain limits are available.

| | |
|--|--|
| <span class="notranslate"> `list-domains <uid>` </span> |list the domain LVEs inside the user LVP of the account with the given numeric <span class="notranslate">UID</span>. Reports <span class="notranslate">`UID ... does not exist`</span> for an unknown account and <span class="notranslate">`No domain limits configured for UID ...`</span> for a known one that has none|
| <span class="notranslate"> `list-domain-limits <user>` </span> |print, as JSON, the limits the kernel holds for each registered domain of the account given by user name or numeric <span class="notranslate">UID</span>. Each row of the <span class="notranslate">`data`</span> array has <span class="notranslate">`domain`</span>, <span class="notranslate">`docroot`</span>, <span class="notranslate">`lve_id`</span>, <span class="notranslate">`in_kernel`</span> and <span class="notranslate">`limits`</span> (<span class="notranslate">`cpu`</span> in hundredths of a percent, <span class="notranslate">`pmem`</span> and <span class="notranslate">`vmem`</span> in bytes, <span class="notranslate">`io`</span> in KB/s). <span class="notranslate">`in_kernel`</span> is <span class="notranslate">`false`</span> and <span class="notranslate">`limits`</span> is <span class="notranslate">`null`</span> while the domain LVE does not exist yet; the site then runs within the account's limits. <span class="notranslate">`domain`</span> is <span class="notranslate">`null`</span> for a registered document root that the panel no longer lists. Supported in lve-utils 6.6.43-1 or later|
| <span class="notranslate"> `allow-domain-limits <user>` </span> |create the user LVP and allow per-domain limits for the named user (idempotent)|
| <span class="notranslate"> `deny-domain-limits <user>` </span> |remove the user LVP and disallow per-domain limits for the named user|
| <span class="notranslate"> `enable-domain-limits <domain>` </span> |register a domain LVE under its owner's LVP. The owner and document root are resolved from the control panel, so only the domain name is given|
Expand All @@ -2925,8 +2926,8 @@ Under a control panel, use the [CageFS Isolates commands](/cloudlinuxos/isolates

| | |
|--|--|
| <span class="notranslate"> `--enter-count` </span> |enable limit for enters count (by default disabled), use only with command "limit". Supported in lve-utils-6.1.2-1 or later. |
| <span class="notranslate"> `--io-and-memory` </span> |enable limit for IO and memory (by default disabled), use only with command "limit". Supported in lve-utils-6.1.2-1 or later. |
| <span class="notranslate"> `--enters-count` </span> |enable limit for enters count (by default disabled), use only with command "limit", before the PID: <span class="notranslate">`lvectl limit --enters-count <PID> <LVE_ID>`</span>. Supported in lve-utils-6.1.2-1 or later. |
| <span class="notranslate"> `--io-and-memory` </span> |enable limit for IO and memory (by default disabled), use only with command "limit", before the PID. Supported in lve-utils-6.1.2-1 or later. |
| <span class="notranslate"> `--cpu=N` </span> |limit <span class="notranslate">`CPU`</span> usage; (deprecated. Use <span class="notranslate">`--speed`</span>)|
| <span class="notranslate"> `--speed=N%` </span> |limit <span class="notranslate">`CPU`</span> usage in percentage; 100% is one core|
| <span class="notranslate"> `--speed=Nmhz\ghz` </span> |limit <span class="notranslate">`CPU`</span> usage in mhz\ghz|
Expand Down Expand Up @@ -2991,7 +2992,7 @@ Under a control panel, use the [CageFS Isolates commands](/cloudlinuxos/isolates
<div class="notranslate">

```
lveps [-p] [-n] [-o <fmt1:width1,...>] [-d] [-c <time>] [-s <style>] [-t] [-h]
lveps [-p] [-n] [-L] [-o <fmt1:width1,...>] [-d] [-c <time>] [-s <style>] [-t] [-h]
```
</div>

Expand All @@ -3001,7 +3002,8 @@ lveps [-p] [-n] [-o <fmt1:width1,...>] [-d] [-c <time>] [-s <style>] [-t] [-h]
|-|-|
|`-p`| to print per-process/per-thread statistics|
|`-n`| to print LVE ID instead of username|
|`-o`| to use formatted output (fmt=id,ep,pid,tid,cpu,mem,io)|
|`-L`| to add the <span class="notranslate">LVP</span> column (the ID of the parent container, `0` if none). Ignored when `-o` is given; add `lvp` to the `-o` format instead. Supported in lve-utils 6.6.40-1 or later|
|`-o`| to use formatted output (fmt=id,lvp,ep,pid,tid,cpu,mem,io; `lvp` requires lve-utils 6.6.40-1 or later)|
|`-d`| to show dynamic cpu usage instead of total cpu usage|
|`-c`| to calculate average cpu usage for &lt;time&gt; seconds (used with `-d`)|
|`-r`| to run under realtime priority for more accuracy (needs privileges)|
Expand All @@ -3018,6 +3020,7 @@ Command like <span class="notranslate">`lveps -p`</span> will display processes
|<span class="notranslate">MEM</span>| The number of megabytes of resident memory in use by LVE/process/thread (shared memory is not included).|
|<span class="notranslate">IO</span> | The number of kilobytes read and written in sum by LVE, or kb/sec if used with `-d`.|
|<span class="notranslate">ID</span> | LVE ID or username.|
|<span class="notranslate">LVP</span> | The numeric ID of the container (LVP) that the LVE is listed under, such as a reseller's LVP or, when per-domain limits are used, the hosting account's LVP; `0` if the LVE is not inside an LVP. Shown with `-L`, or when `lvp` is included in the `-o` format.|
|<span class="notranslate">EP</span> | The number of entry processes inside LVE.|
|<span class="notranslate">COM</span> | Command name for this process.|
|<span class="notranslate">PID</span> | <span class="notranslate">PID</span> of the process.|
Expand Down Expand Up @@ -3098,7 +3101,7 @@ testuser5 0 2 2 1% 52 0 0
|<span class="notranslate">`--update-license`</span>|updates license|
|<span class="notranslate">`--update-new-key`</span>|updates license with new key|
|<span class="notranslate">`--check-license`</span>|check license. Returns OK if license is not older than 3 days, error message otherwise|
|<span class="notranslate">`-q`</span>|check license. Returns 0 if license is not older than 3 days, 1 otherwise|
|<span class="notranslate">`--check-license -q`</span>|check license quietly (<span class="notranslate">`--quiet`</span> is the long form of <span class="notranslate">`-q`</span>). Returns 0 if license is not older than 3 days, 1 otherwise. <span class="notranslate">`-q`</span> has effect only with <span class="notranslate">`--check-license`</span>; on its own it prints an error and returns 1|
|<span class="notranslate">`--no-valid-license-screen`</span>|returns no valid license found screen|
|<span class="notranslate">`--license-out-of-date-email`</span>|returns License out of Date Email.|
|<span class="notranslate">`--check-openvz`</span>|returns enviroment id|
Expand Down
27 changes: 22 additions & 5 deletions docs/cloudlinuxos/isolates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -595,6 +595,8 @@ $ isolatectl site-isolation list

Per-domain resource limits allow end users to set and apply individual CPU, memory, I/O, and process limits for each isolated domain. Domain limits require site isolation to be enabled first.

With lve-utils 6.6.43-1 or later, a failed `isolatectl limits` or [`isolatectl stats`](#per-domain-statistics) command exits with a non-zero status and returns JSON with `"result": "error"`, a `code` and a human-readable `message`. Check `code` rather than the message text. The codes are `not_allowed` (for example, per-domain limits are not enabled for the account), `domain_not_owned`, `not_isolated` (the domain has no registered domain LVE id yet), `invalid_value`, `config_unreadable` (`~/.lve/domains.json` cannot be read; details are in `~/.lve/isolatectl.log`), `kernel_error`, `backend_unavailable` and `internal_error`.

##### List Domain Limits

```
Expand All @@ -618,7 +620,8 @@ $ isolatectl limits list
"domains": [
{
"name": "example.com",
"lve_id": 1000,
"lve_id": 60057,
"owner_uid": 1000,
"limits": {"cpu": 2500, "pmem": 1048576}
}
]
Expand All @@ -630,13 +633,16 @@ $ isolatectl limits list --domain example.com
"domains": [
{
"name": "example.com",
"lve_id": 1000,
"lve_id": 60057,
"owner_uid": 1000,
"limits": {"cpu": 2500, "pmem": 1048576}
}
]
}
```

`lve_id` is the domain's own LVE id, the one that `lvectl list-domains` and `isolatectl stats` report, and `owner_uid` is the account's UID. `lve_id` is `null` for a domain whose domain LVE id cannot be resolved, for example because `lvectl enable-domain-limits` was never run for it.

***

##### Set Domain Limits
Expand All @@ -662,6 +668,8 @@ Stores per-domain limits in the user's config and applies them to the kernel.

At least one limit parameter is required.

Memory limits are applied in whole 4 KiB pages (rounded down), so set `--pmem` and `--vmem` either to `0`, which leaves the domain bounded only by its account, or to at least `4096` bytes. With lve-utils 6.6.43-1 or later, a smaller non-zero memory value is rejected with `invalid_value`, as is a value that the kernel refuses, such as a CPU limit above the server's capacity; a rejected value is not saved.

**Example:**

```
Expand Down Expand Up @@ -982,6 +990,7 @@ The underlying <span class="notranslate">`lvectl`</span> commands are available
|<span class="notranslate">`lvectl enable-domain-limits <domain>`</span> | Register a domain LVE. The owner and document root are resolved from the control panel.|
|<span class="notranslate">`lvectl disable-domain-limits <domain>`</span> | Unregister the domain LVE and remove its registry entry.|
|<span class="notranslate">`lvectl list-domains <uid>`</span> | List the domain LVEs of the account with the given numeric UID.|
|<span class="notranslate">`lvectl list-domain-limits <user>`</span> | Show the per-domain limits in force, read from the registry and the kernel (lve-utils 6.6.43-1 or later).|
|<span class="notranslate">`lvectl regenerate-domains --username <user> ...`</span> | Refresh the domain configuration and id mapping after a rename or document root change.|

See [lvectl](/cloudlinuxos/command-line_tools/#lvectl) for the full syntax.
Expand All @@ -994,14 +1003,14 @@ After changing a domain name or document root outside a supported control panel,

### Setting per-domain limits

Per-domain limits are set by the account owner with [`isolatectl limits`](#per-domain-resource-limits), not by the administrator: there is no <span class="notranslate">`lvectl`</span> command that sets an individual domain's limits. Administrators control the account-level limits, which bound every domain underneath them.
Per-domain limits are set by the account owner with [`isolatectl limits`](#per-domain-resource-limits), not by the administrator: there is no <span class="notranslate">`lvectl`</span> command that sets an individual domain's limits. Administrators control the account-level limits, which bound every domain underneath them. To see the per-domain limits in force, run <span class="notranslate">`lvectl list-domain-limits <user>`</span> as root (lve-utils 6.6.43-1 or later). It reads the registry and the kernel rather than <span class="notranslate">`~/.lve/domains.json`</span>, which the account can edit.

Where the state lives:

| | |
|-|-|
|<span class="notranslate">`~/.lve/domains.json`</span> | The account's per-domain limits and its list of isolated domains. This is the file <span class="notranslate">`isolatectl limits apply`</span> reads when re-applying limits to the kernel.|
|<span class="notranslate">`/etc/container/lvd_ids/<uid>`</span> | The account's domain-name-to-LVE-id registry.|
|<span class="notranslate">`/etc/container/lvd_ids/<uid>`</span> | The account's registry of domain LVE ids, keyed by document root.|

### Viewing per-domain usage

Expand Down Expand Up @@ -1069,10 +1078,18 @@ The account exists but has no isolated domains. Where CloudLinux Isolates is ava

**A domain's statistics stopped after a rename or a document root change**

The domain's registry entry is keyed on its document root. Changes made through a supported control panel are handled by the panel hooks; if the change was made outside the panel, refresh the mapping by hand:
The domain's registry entry is keyed on its document root. Changes made through a supported control panel are handled by the panel hooks; if the change was made outside the panel, refresh the mapping by hand. After a rename:

```
lvectl regenerate-domains --username <user> --domain <new> --old-domain <old>
```

After a document root change, give the previous document root instead, and add <span class="notranslate">`--old-domain <old>`</span> if the name also changed:

```
lvectl regenerate-domains --username <user> --domain <domain> --old-docroot <old_docroot>
```

<span class="notranslate">`<old_docroot>`</span> must match the previously registered document root exactly, as the control panel reported it; otherwise the registry is not updated and no error is reported. With lve-utils 6.6.43-1 or later, <span class="notranslate">`lvectl list-domain-limits <user>`</span> shows that document root as the <span class="notranslate">`docroot`</span> of a row whose <span class="notranslate">`domain`</span> is <span class="notranslate">`null`</span>. A document root change gives the domain a new domain LVE id.

***