1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
=================================================
Service Management Requirements for NETCONF APK
=================================================
:Author:
A. Wilcox
:Copyright:
© 2020 Adélie Software in the Public Benefit, Inc. NCSA license.
:Status:
Draft
Introduction
============
This document defines the service management module requirements for the
NETCONF for APK Distributions system.
Definition of terms
-------------------
* ``NETCONF APK``: The NETCONF for APK Distributions system, including the
base server and modules contained in the netconfapk source distribution.
* ``service``: A long-running process (or ``daemon``) on a system.
* ``service manager``: The component of the operating system that controls
daemons.
Intended audience
-----------------
This document is primarily intended to be read by the implementors of
NETCONF APK. It is also intended to be read by implementors of external
NETCONF APK modules that need to interact with the service manager. It
may additionally be useful for documentation writers to inform network
administrators who are interacting with NETCONF APK about how its service
management module functions.
Purpose
=======
The service management module allows NETCONF APK to query service status,
start and stop services, list running services, and list available
services on a system.
The service management module provides two methods of interaction. The
first is a well-defined Python API, used by NETCONF APK to provide other
module functionality. For example, this includes /system/ntp/enabled.
The second is a YANG model that allows network administrators to directly
interrogate the system via NETCONF on current service status, and to
request services to start and stop in a service-independent manner using
a well-defined RPC.
Data model definition
=====================
A service has at least the following properties:
* ``name``, the name of the service.
* ``description``, a meaningful description of what the service does or
provides. This may be the name of the service if the service
description does not provide or support a description field.
* ``enabled``, a boolean value describing whether the service is enabled
or not. When a service is enabled, it is automatically started when the
system boots.
* ``status``, an enumeration value of the current status of the service.
The ``ServiceStatus`` enumeration has at least the following values:
* ``stopped``: the service is not presently started.
* ``starting``: the service is in the process of starting up.
* ``running``: the service is presently running.
* ``stopping``: the service is in the process of stopping.
* ``crashed``: the service was started, but stopped unexpectedly.
Not all service managers support this enumeration value.
Additional values may be defined depending on the service manager
currently in use on the system.
* ``start-time``, a timestamp when the service was started. This property
is only available if ``status`` is ``started``.
Additional properties may be available depending on the service manager
currently in use on the system.
All property values are provided directly by the service manager; the
NETCONF APK service management module does not attempt any form of
translation or emulation of the values returned by the service manager.
Additionally, ``status`` state transitions are explicitly defined by the
service manager currently in use on the system; no guarantee is made on
the ordering of transitions nor which transitions are valid and invalid.
Python API
==========
The service management module is loaded as any other NETCONF APK module.
It implements the ``http://netconf.adelielinux.org/ns/service`` namespace.
Other modules access the service management Python API by retrieving a
handle to the module implementing that namespace, and then calling well-
defined methods on it.
``service_list()``
------------------
This method takes no arguments.
Returns an iterable of ``Service`` objects as described in the section
`Python Service objects`_.
``info(service)``
-----------------
This method takes a single argument, ``service``. This argument is a
string and must contain the name of a service present on the system.
This method returns the Service object associated with the service given
as the argument, as described in the section `Python Service objects`_.
If the argument is not a string or does not the contain the name of a
service present on the system, a Python ``NameError`` will be raised.
Python Service objects
----------------------
A Python ``Service`` object has all properties defined in the section
`Data model definition`_. Any dash (``-``) characters in a property name
are replaced with underscore (``_``) characters.
The ``Service`` object contains the following methods:
``status()``
~~~~~~~~~~~~
This method queries the service manager for the current status of the
service associated with the Service object.
This method returns a value from the ``ServiceStatus`` enumeration defined
under the ``status`` property in the `Data model definition`_ section.
``start()``
~~~~~~~~~~~
This method starts the service associated with the Service object.
This method has no effect if the status of the service is ``starting`` or
``started``.
This method returns immediately with no value. To determine if a service
started successfully, you must query the service's status.
``stop()``
~~~~~~~~~~
This method stops the service associated with the Service object.
This method has no effect if the status of the service is ``stopping``,
``stopped`` or ``crashed``.
This method returns immediately with no value. To determine if a service
stopped successfully, you must query the service's status.
``reload()``
~~~~~~~~~~~~
This method reloads the service associated with the Service object.
This method has no effect unless the status of the service is ``started``.
This method returns immediately with no value.
``restart(full)``
~~~~~~~~~~~~~~~~~
This method restarts the service associated with the Service object.
This method has no effect if the status of the service is ``stopping`` or
``starting``.
If the status of the service is not ``started``, the service will be
started without a stop attempt.
The argument ``full`` determines if the restart is a full restart or not.
The meaning of a full restart is implementation-defined. The argument
defaults to ``True`` if it is not specified.
This method returns immediately with no value. To determine if a service
restarted successfully, you must query the service's status.
YANG Model
==========
Data model
----------
The data model for system services has the following structure:
::
+--rw services
+--rw service* [name]
+--rw name string
+--ro description? string
+--rw enabled boolean
+--ro status service-status
+--ro start-time? yang:date-and-time
Module
------
See `adelie-services.yang`_.
.. _`adelie-services.yang`: ../yang-modules/adelie-services.yang
|
