# Unit设计说明书

## 1    概述

unit是所有sysmaster管理的subunit的基础，sysmaster通过配置文件来定义每个具体subunit实例的行为，unit负责出所有subunit运行时功能行为的定义，以及设置为开机自动时需要的信息

### 目的

本文用描述unit支持的属性（通过配置文件定义），并清晰描述每个定义的配置文件的具体目的，和使用的场景。并记录unit每个配置演进过程。

## 2    特性需求概述

表1：特性需求列表

| 需求编号 | 需求名称           | 特性描述                                                                                          | 优先级 |
| -------- | ------------------ |--------------------------------------------------- | ------ |
| 1        | 支持unit基本功能定义 | 支持定义unit运行时公共行为的定义                     | 高     |
| 2        | 支持unit设置为开机启动功能定义  | 定义unit设置为开机时，需要执行的动作       | 高     |

## 3    需求场景分析

sysmaster通过unit管理操作系统中各类服务的生命周期，每类服务运行时需要执行生命类型的操作，通过配置文件来进行定义，对公共的行为进行同一的定义，将重复工作降到最低，此部分需求分析，需要结合系统维护过程中经常用到的属性，并需要考虑和systemd兼容的兼容性

### 3.2    特性场景分析

系统中的服务执行的主要动作包含load、reload、start、restart、stop并且还需要支持对于具体服务状态的查询，unit公共属性用于定义unit执行具体动作是的行为，并且unit支持一些运行时的依赖关系，也需要在unit配置文件中进行定义，参考日常使用情况，以及兼容性考虑，unit公共属性分成两个部分：

1. [Base]

| 配置名称     | 值类型 | 配置项说明                     | 使用场景                          | 优先级 | 是否支持 |容器|虚机|物理机|
| :-------    | :----- | :--------                     | :------------------------------  | :-----  | :--- | :--- | :--- | :--- |
| Description | String | unit的描述，用于说明unit的功能  | 使用sctl命令查询unit信息时用于显示 | 高  | 是 |√|√|√|
| Documentation| String | 配置具体服务的帮助文档          | 显示配置的帮助文档                 | 低    | 否 |√|√|√|
| Requires    | String | 可以配置多个，之间使用空格隔开   | 配置依赖的其他unit，并支持同步启动，unit如果状态"failed"，则此单元启动失败 | 高 | 是 |√|√|√|
|Wants        | String | 可以配置多个，之间使用空格隔开   |require弱化版本，不受被依赖单元的启动状态影响| 高 | 是 |√|√|√|
|Before       | String | 可以配置多个，之间使用空格隔开   | 如果该字段指定的 Unit 也要启动，那么必须在当前 Unit 之后启动 |高|是|√|√|√|
|After        |String  | 可以配置多个，之间使用空格隔开   |如果该字段指定的 Unit 也要启动，那么必须在当前 Unit 之前启动 |高|是|√|√|√|
|Conflicts    |String  | 可以配置多个，之间使用空格隔开 |   这里指定的 Unit 不能与当前 Unit 同时运行|高|是|√|√|√|
|Condition... | String  |                              |当前 Unit 运行必须满足的条件，否则跳过运行，保持当前状态不变，不会影响require依赖此unit的启动|高|是|√|√|√|
|Assert...    | String  |                             |当前 Unit 运行必须满足的条件，否则会报启动失败|高|是|√|√|√|
|DefaultDependencies| boolean |是否增加默认依赖，默认为yes |不同类型的unit，有不同的默认依赖，具体有各个子类分析|高|是|√|√|√|
|OnFailureJobMode   |enumerate|                      |                                          |高|是|√|√|√|
|StartLimitInterval |number   |                      |                                          |高|是|√|√|√|
|StartLimitBurst    |number   |                      |                                          |高|是|√|√|√|
|StartLimitAction   |enumerate|                      |                                          |高|是|√|√|√|
|SuccessAction      |enumerate|                      |                                          |高|是|√|√|√|
|FailureAction      |enumerate|                      |                                          |高|是|√|√|√|
|BindsTo            |String   |                      | 与Requires类似，它指定的 Unit 如果退出，会导致当前 Unit 停止运行|低|否|X|X|X|
|AllowIsolate       | bool    |      默认值为no       | 为兼容sysv的runlevel切换，支持在线切换，使用不广，暂时不支持  |低|否|X|X|X|
|IgnoreOnIsolate| bool | 默认值为yes | 支持target切换时，该服务不停止运行  |低|否|X|X|X|

1. [Dist]

| 配置名称     | 值类型 | 配置项说明                     | 使用场景                          | 优先级 | 是否支持 |容器|虚机|物理机|
| :-------    | :----- | :--------                     | :------------------------------  | :-----  | :--- | :--- | :--- | :--- |
|WantedBy| String | 可以配置多个，之间使用空格隔开 | 主动期望被其他单元wanted，触发自己启动 |高|是|√|√|√|
|RequiredBy| String | 可以配置多个，之间使用空格隔开 |主动期望被其他单元required，触发自己启动 |高|是|√|√|√|

### 3.3   特性影响分析

## 4 特性/功能实现原理

### 4.1 总体方案

    要实现通过unit管理系统中的服务，包含以下步骤：
    1. 解析unit的配置文件，转换成unit对象
    2. 执行unit对应的动作
    整体模块划分包括：
    1. load模块，将配置文件转换成unit
    2. unit_dataStore，保存unit的状态
    3. unit模块，包含unit属性
