### Localization of Alterator Entry Keys

Source: https://github.com/alterator/alterator-entry/blob/master/doc/alterator-for-intranet.txt

Example demonstrating how the Alterator system resolves localized keys based on the current LC_MESSAGES environment variable. It shows the priority order for selecting the appropriate 'Name' value.

```ini
Name=Foo
Name[sr_YU]=...
Name[sr@Latn]=...
Name[sr]=...
```

--------------------------------

### Alterator-Entry CLI: Get Field Value (Bash)

Source: https://context7.com/alterator/alterator-entry/llms.txt

Uses the 'alterator-entry get' command to retrieve values of fields from backend configuration files. Supports simple fields, interfaces, and nested values using dot notation.

```bash
# Получение значения простого поля
alterator-entry get /usr/share/alterator/backends/lister.backend name
# Вывод: lister

# Получение значения интерфейса
alterator-entry get /usr/share/alterator/backends/lister.backend interface
# Вывод: lister1

# Получение вложенного значения через точечную нотацию
alterator-entry get /usr/share/alterator/backends/lister.backend methods.List.execute
# Вывод: ls {param}

# Получение списка методов (ключей таблицы)
alterator-entry get /usr/share/alterator/backends/lister.backend methods
# Вывод:
# List
# ListAllLong

# Получение таймаута метода
alterator-entry get /usr/share/alterator/backends/lister.backend methods.ListAllLong.timeout
# Вывод: 1000
```

--------------------------------

### Define Desktop Entry File Structure

Source: https://github.com/alterator/alterator-entry/blob/master/doc/alterator-for-intranet.txt

A standard Desktop Entry file structure defining application metadata, execution paths, and custom actions. This format is used by Linux desktop environments to launch applications and manage menu entries.

```ini
[Desktop Entry]
Version=1.0
Type=Application
Name=Foo Viewer
Comment=The best viewer for Foo objects available!
TryExec=fooview
Exec=fooview %F
Icon=fooview
MimeType=image/x-foo;
Actions=Gallery;Create;

[Desktop Action Gallery]
Exec=fooview --gallery
Name=Browse Gallery

[Desktop Action Create]
Exec=fooview --create-new
Name=Create a new Foo!
Icon=fooview-new
```

```ini
[Desktop Entry]
Type=Application
Name=Test
Icon=/home/luke/Pictures/icon.png
Exec=/home/luke/bin/test.sh
Terminal=false
Categories=Development;
Actions=ActionTest;

[Desktop Action ActionTest]
Name=Action Test
Exec=/home/luke/bin/test-action.sh
```

--------------------------------

### Utility Parameters

Source: https://github.com/alterator/alterator-entry/blob/master/doc/README.md

Standardized utility flags used for monitoring and controlling service deployment states.

```APIDOC
## Utility Parameters

### Description
Standard flags for service status and deployment control.

### Parameters
- **deployed** (boolean) - Context: status - Indicates if service is deployed.
- **started** (boolean) - Context: status - Indicates if service is running.
- **force_deploy** (boolean) - Context: deploy - Forces deployment, requires enable_force_deploy=true.
```

--------------------------------

### Alterator Entry Configuration

Source: https://github.com/alterator/alterator-entry/blob/master/doc/README.md

This section details the various configuration parameters available for the Alterator Entry API, controlling aspects like output handling, limits, signal names, timeouts, and thread limits.

```APIDOC
## Alterator Entry Configuration Parameters

### Description

This endpoint provides configuration options for controlling the execution of processes managed by Alterator. It allows for detailed customization of how standard output (stdout) and standard error (stderr) are handled, including returning them as strings or bytes, setting limits, redirecting them to signals, and managing timeouts and thread concurrency.

### Method

POST (Implied, as these are configuration parameters)

### Endpoint

/git_altlinux_space/alterator_alterator-entry

### Parameters

#### Request Body Parameters

- **stdout_strings** (boolean) - Enabled/Disabled - Allows returning stdout as an array of strings.
- **stdout_bytes** (boolean) - Enabled/Disabled - Allows returning stdout as an array of bytes. Enabling this disables string return and signals.
- **stderr_strings** (boolean) - Enabled/Disabled - Allows returning stderr as an array of strings.
- **stdout_byte_limit** (numeric) - Optional - Maximum byte limit for stdout. Default is 524288. Range: 0 to 2147483647.
- **stdout_strings_limit** (numeric) - Optional - Maximum string limit for stdout. Default is 524288.
- **stderr_strings_limit** (numeric) - Optional - Maximum string limit for stderr. Default is 524288.
- **stdout_signal_name** (string) - Optional - Name of the signal to redirect stdout to.
- **stderr_signal_name** (string) - Optional - Name of the signal to redirect stderr to.
- **action_id** (string) - Optional - Polkit unique identifier for the method.
- **timeout** (numeric) - Optional - Timeout in seconds for the process. Default is 60. If 0 or less, no timeout is set.
- **thread_limit** (numeric) - Optional - Maximum number of concurrent instances of the method. Default is 1.

### Request Example

```json
{
  "stdout_strings": true,
  "stderr_strings": true,
  "stdout_byte_limit": 1048576,
  "timeout": 120,
  "thread_limit": 5
}
```

### Response

#### Success Response (200)

- **status** (string) - Indicates the success of the configuration update.

#### Response Example

```json
{
  "status": "success"
}
```

### Further Information

For a detailed explanation, refer to the [README-ru.md](https://gitlab.basealt.space/alt/alterator-manager/-/blob/master/docs/README-ru.md).

### Examples

- [autogenerated-legacy-net-eth.backend](../examples/backends/autogenerated-legacy-net-eth.backend)
- [backend-example.user.backend](../examples/backends/backend-example.user.backend)
```

--------------------------------

### Validate configuration files via CLI

Source: https://context7.com/alterator/alterator-entry/llms.txt

Demonstrates how to use the alterator-entry CLI tool to validate service files and integrate validation checks into shell scripts.

```bash
# Validate a service file
alterator-entry validate /path/to/invalid.service

# Use in a script
if alterator-entry validate "$FILE" 2>/dev/null; then
    echo "Файл валиден"
else
    echo "Ошибка валидации"
fi
```

--------------------------------

### Define D-Bus Application Interface

Source: https://github.com/alterator/alterator-entry/blob/master/doc/alterator-for-intranet.txt

An XML definition of the org.freedesktop.Application interface used for D-Bus activation. It includes methods for activating the application, opening URIs, and triggering specific actions with platform data.

```xml
<interface name='org.freedesktop.Application'>
  <method name='Activate'>
    <arg type='a{sv}' name='platform_data' direction='in'/>
  </method>
  <method name='Open'>
    <arg type='as' name='uris' direction='in'/>
    <arg type='a{sv}' name='platform_data' direction='in'/>
  </method>
  <method name='ActivateAction'>
    <arg type='s' name='action_name' direction='in'/>
    <arg type='av' name='parameter' direction='in'/>
    <arg type='a{sv}' name='platform_data' direction='in'/>
  </method>
</interface>
```

--------------------------------

### Resource Management

Source: https://github.com/alterator/alterator-entry/blob/master/doc/README.md

Defines system resources such as files, directories, systemd units, and network ports.

```APIDOC
## Resource Definition

### Description
Describes system resources and their associated properties for service management.

### Fields
- **display_name** (string) - Optional - UI label.
- **comment** (string) - Optional - Description.
- **type** (string) - Required - Values: file, directory, systemd_unit, port.
- **path** (dictionary) - Required for file/directory - Path definition.
- **unit_name** (dictionary) - Required for systemd_unit - Unit identifier.
- **inet_service** (dictionary) - Required for port - Port number.
- **tcp** (boolean) - Required - TCP protocol usage.
- **udp** (boolean) - Required - UDP protocol usage.

### Resource Properties
- **value** (string/integer) - Required - Property value.
- **parameter** (string) - Optional - Link to a parameter for override.
```

--------------------------------

### Service Parameter Definitions

Source: https://github.com/alterator/alterator-entry/blob/master/doc/README.md

Defines the structure and constraints for service parameters, including validation rules and context-specific requirements.

```APIDOC
## Parameter Schema Definition

### Description
Defines how parameters are structured, including validation hints, default values, and context-aware requirements.

### Parameters
- **min** (integer) - Optional - Minimum value for integer parameters.
- **max** (integer) - Optional - Maximum value for integer parameters.
- **validation_hint** (dictionary) - Optional - Description of allowed values.
- **default** (string) - Optional - Default value.
- **constant** (boolean) - Optional - If true, parameter is hidden.
- **context** (stringlist) - Required - Scenarios: deploy, configure, restore, backup, diag, status.
- **required** (stringlist) - Optional - Defines mandatory status per context.

### Object-specific Fields
- **properties** (dictionary) - Required if prototype not set - Child parameters.
- **prototype** (string) - Required if properties not set - Reference to another parameter as a prototype.
```

--------------------------------

### Define Distribution Edition settings

Source: https://context7.com/alterator/alterator-entry/llms.txt

Defines an Edition configuration, specifying supported architectures, kernel flavors, and organizational sections for components.

```toml
type = "Edition"
name = "edition_domain"
arches = ["x86_64", "aarch64", "i586"]
kflavours = { default = "6.12", options = ["6.6", "6.12"] }

[sections.base]
components = ["build_essentials", "rust_dev_tools"]
```

--------------------------------

### Define D-Bus Backend interface

Source: https://context7.com/alterator/alterator-entry/llms.txt

Defines a Backend configuration file that maps D-Bus methods to system commands via alterator-module-executor.

```toml
name = "lister"
type = "Backend"
module = "executor"
interface = "lister1"

[methods.List]
execute = "ls {param}"
stdout_strings = true
action_id = "List"
timeout = 100
```

--------------------------------

### Configure Service parameters and resources

Source: https://context7.com/alterator/alterator-entry/llms.txt

Defines a Service configuration including diagnostic tools, typed parameters with validation rules, and system resources.

```toml
type = "Service"
name = "example_service"

[parameters.hostname]
type = "string"
pattern = "^[a-zA-Z0-9-]+$"
default = "localhost"

[resources.config]
type = "file"
path.value = "/etc/example/config.toml"
```

--------------------------------

### Extract Packages from Component (Python)

Source: https://context7.com/alterator/alterator-entry/llms.txt

Extracts package names from a component's package dictionary using specified filters. It automatically appends kernel version suffixes for kernel modules. Dependencies include 'alterator_entry' and 'tomlkit'.

```python
from alterator_entry import extract_packages_from_component, PackagesFilterOptions
import tomlkit

# Загрузка компонента
with open("/usr/share/alterator/components/fortune_cow_rainbow/fortune_cow_rainbow.component", "rb") as f:
    component = tomlkit.load(f)

# Определение фильтра
options = PackagesFilterOptions(
    kflavours=["6.12"],
    arch="x86_64",
    section=None,
    desktop=None,
    language="ru",
    image_ignore=True
)

# Извлечение пакетов
packages = extract_packages_from_component(
    component["packages"].value,
    options
)
print(packages)
# ['fortune', 'fortunes-ALT', 'fortunes-ALT-lists', 'fortunes-ALT-bugzilla',
#  'fortunes-ALT-irc', 'fortunes-LOR', 'cowsay', 'lolcat']

# Пример с kernel_module пакетом
packages_dict = {
    "nvidia-driver": {"kernel_module": True},
    "mesa": {},
    "vulkan-tools": {"arch": ["x86_64", "aarch64"]}
}

options_kernel = PackagesFilterOptions(
    kflavours=["6.12", "6.6"],
    arch="x86_64",
    section=None,
    desktop=None,
    language="ru",
    image_ignore=True
)

result = extract_packages_from_component(packages_dict, options_kernel)
print(result)
# ['nvidia-driver-6.12', 'nvidia-driver-6.6', 'mesa', 'vulkan-tools']
```

--------------------------------

### Define Component packages and architecture filters

Source: https://context7.com/alterator/alterator-entry/llms.txt

Describes a Component file used to group packages with specific constraints like architecture, desktop environment, and language.

```toml
type = "Component"
name = "development_tools"

[packages]
gcc = {}
perf = { arch = ["x86_64"] }
gdb = { exclude_arch = ["e2k"] }
kdevelop = { desktop = "KDE6" }
```