Commit c0344fc5 authored by Eric Vidal's avatar Eric Vidal 💬

update doc

parent a2637534
......@@ -20,7 +20,7 @@
<p>
66-update is a program that should be used rarely. At upgrade/downgrade time, the inner file format
used to retrieve informations of tree,service database currently in use, can differ between two versions.
In this case, service databases and trees need to be rebuild to match the new format.The 66-update program makes
In this case, service databases and trees need to be rebuild to match the new format. The 66-update program makes
a complete transition of trees and the live directory using a old 66 format (the one being replaced) with the new
66 format.
......@@ -56,7 +56,13 @@
</li>
<li>
<tt><b>&#8209;l&nbsp;<em>live</em></b></tt> : an absolute path. Sends the signal to a <em>scandir</em> at <em>live</em>. Default is <tt>%%livedir%%</tt>. The default can also be changed at compiling time by passing the <tt>&#8209;&#8209;livedir=<em>live</em></tt> option to <tt>./configure</tt>. Should be available within a writable filesystem - likely a RAM filesystem.
<tt><b>&#8209;l&nbsp;<em>live</em></b></tt> : an absolute path.
Sends the signal to a <em>scandir</em> at <em>live</em>.
Default is <tt>%%livedir%%</tt>. The default can also be
changed at compiling time by passing the
<tt>&#8209;&#8209;livedir=<em>live</em></tt> option to
<tt>./configure</tt>. Should be available within a writable
filesystem - likely a RAM filesystem.
</li>
<li>
......
......@@ -229,21 +229,21 @@ Valid _key_ names:
A service declared as optional dependencies is not mandatory.
The parser will look at all trees if the corresponding service is
already enabled:++
If It the case, it warn the user and do nothing.++
If not, it tries to find the corresponding frontend file.++
If the frontend service file is found, it enable it.++
If it not found it, it warn the user and do nothing.
If enabled, it will warn the user and do nothing.++
If not, it will try to find the corresponding frontend file.++
If the frontend service file is found, it will enable it.++
If it not found it, it will warn the user and do nothing.
The *order* is of importance. The first service found will be used
and the parse process of the field will be stopped.
So, you can considere *@optsdepends* field as:
"enable one on this service or none".
We talk about enable process here. The start process will not take care
about optional dependencies. If fooA on treeA have an optional dependency fooB which is
declared on treeB, it's the responsability of the sysadmin to start first
treeB then treeA. *66-intree* give you
the order of the start with the field *Start after*.
@optsdepends only affects the enable process. The start process will
consider optional dependencies. If fooA on treeA have an optional
dependency fooB which is declared on treeB, it's the responsability
of the sysadmin to start first treeB then treeA. *66-intree* can give
you the start order with the field *Start after*.
*@extdepends*++
Declare external dependencies of the service.++
......@@ -254,23 +254,23 @@ Valid _key_ names:
*oneshot*. Services of type *classic* are not allowed.
A service declared as external dependencies is mandatory.
The parser will look at all trees if the corresponding service is
The parser will search through all trees whether the corresponding service is
already enabled:++
If It the case, it warn the user and do nothing.++
If not, it tries to find the corresponding frontend file.++
If the frontend service file is found, it enable it.++
If it not found it, the process is stopped and *66-enable* exit 111.
If enabled, it will warn the user and do nothing.++
If not, it will try to find the corresponding frontend file.++
If the frontend service file is found, it will enable it.++
If not, the process is stopped and *66-enable* exit 111.
This process is made for all services declared in the field.
So, you can considere @extdepends field as:
"enable the service if it not already declared on a tree".
We talk about enable process here. The start process will not take care
about external dependencies. If fooA on treeA have an external dependency fooB which is
declared on treeB, it's the responsability of the sysadmin to start first
treeB then treeA. *66-intree* give you
the order of the start with the field *Start after*.
@extdepends only affects the enable process. The start process will not consider
external dependencies. If fooA on treeA has an external dependency fooB which is
declared on treeB, it's the responsibility of the sysadmin to start first
treeB then treeA. *66-intree* will give you
the start order with the field *Start after*.
*@contents*++
Declare the contents of a bundle service.++
......
......@@ -28,14 +28,14 @@
enable colorization.
*-n*
do not display the field name.
do not display the field name(s) specified.
*-o*
comma separated list of fields to display. If this option is not passed,
*66-inservice* will display all fields.
*-g*
shows the dependency list of the _service_ as a graph instead of a list.
shows the dependency list of the _service_ as a hierarchical graph instead of a list.
*-d* _depth_
Limits the depth of the dependency list visualisation; default is 1.
......@@ -45,7 +45,8 @@
Shows the dependency list of _service_ in reverse mode.
*-t* _tree_
only searches the _service_ at the specified _tree_.
only searches the _service_ at the specified _tree_, when the same
service may be enabled in more trees.
*-p* _nline_
prints the _nline_ last lines from the log file of the _service_.
......@@ -110,26 +111,26 @@ The command "66-inservice 00" run as root user on _Obarun_'s default system
displays the following, where *00* is a service contained in the tree *boot*:
```
Name : 00
In tree : boot
Status : enabled, nothing to display
Type : bundle
Description : Set the hostname and mount filesystem
Source : %%service_packager%%/boot/mount/00
Live : %%livedir%%/tree/0/boot/servicedirs/00
Depends on : system-hostname mount-run populate-run mount-tmp
populate-tmp mount-proc mount-sys populate-sys
mount-dev mount-pts mount-shm populate-dev
mount-cgroups
Optional depends : None
External depends : None
Start script : None
Stop script : None
Environment source : None
Environment file : None
Log name : None
Log destination : None
Log file : None
Name : 00
In tree : boot
Status : enabled, nothing to display
Type : bundle
Description : Set the hostname and mount filesystem
Source : %%service_packager%%/boot/mount/00
Live : %%livedir%%/tree/0/boot/servicedirs/00
Dependencies : system-hostname mount-run populate-run mount-tmp
populate-tmp mount-proc mount-sys populate-sys
mount-dev mount-pts mount-shm populate-dev
mount-cgroups
Optional dependencies : None
External dependencies : None
Start script : None
Stop script : None
Environment source : None
Environment file : None
Log name : None
Log destination : None
Log file : None
```
......@@ -144,7 +145,7 @@ where the dependency list is diplayed as a graph:
```
Status : enabled, up (pid 938) 34652 seconds
Depends on : /
Dependencies : /
├─(933,Enabled,longrun) dbus
└─(929,Enabled,longrun) connmand-log
......
......@@ -35,7 +35,7 @@
enable colorization.
*-n*
do not display the field name.
do not display the field name(s) specified.
*-o*
comma separated list of fields to display. If this option is not passed,
......@@ -77,7 +77,7 @@
*symlinks*
Displays the target of the _tree_'s symlinks.
*contains*
*contents*
Displays the contents of the _tree_.
# COMMAND AND OUTPUT EXAMPLE
......@@ -131,10 +131,10 @@ without starting it. Right after a boot, each tree should point to *source*.
The field *Contains* gives you a list of all services enabled in the _tree_.
You can display the contents list as a graph and only these fields using
the command "66-intree -o contains -g boot":
the command "66-intree -o contents -g boot":
```
Contains : /
Contents : /
├─(253,Enabled,classic) tty12
├─(0,Enabled,oneshot) system-hostname
├─(0,Enabled,oneshot) mount-run
......
......@@ -10,10 +10,10 @@
# DESCRIPTION
*66-tree* will dynamically handle a set of any kind of services in _tree_.
The _tree_ will be handled for the user running the process.
Any _tree_ is completely independent from another. If you want to know what trees
are currently available on the system use *66-intree*(1) tool.
*66-tree* will create, destroy, or modify a _tree_ which dynamically handles services.
*66-tree* will handle the _tree_ only for the user running the process (root/user).
Any _tree_ is completely independent from another. If you want to know
what trees are currently available on the system use the *66-intree*(1) tool.
# OPTIONS
......@@ -22,14 +22,14 @@ are currently available on the system use *66-intree*(1) tool.
*-v* _verbosity_
Increases/decreases the verbosity of the command.++
*1* : (Default) Only print error messages.++
*2* : Also print warning messages.++
*3* : Also print tracing messages.++
*4* : Also print debugging messages.
*1* : (Default) Only prints error messages.++
*2* : Also prints warning messages.++
*3* : Also prints tracing messages.++
*4* : Also prints debugging messages.
*-l* _live_
An absolute path. It used in conjunction with *-U* and *-R* options
to specify the live directory place of _tree_. It has no effects otherwise.
An absolute path. It is used in conjunction with *-U* and *-R* options
to specify the live directory location of a _tree_. It has no effects otherwise.
Default is *%%livedir%%*. The default can also be changed at compile-time
by passing the \--livedir=_live_ option to *./configure*. Should be under
a writable filesystem - likely a RAM filesystem.
......@@ -48,7 +48,7 @@ are currently available on the system use *66-intree*(1) tool.
database at compilation time.
*-d* _user_
Denies _user_ to deal with the given _tree_. Must match an existing username
Denies _user_ to deal with the specified _tree_. Must match an existing username
on the system. Several users can be denied by separating their names with a
comma. Useful to revoke access that has been given before with *-a*.
......@@ -65,7 +65,7 @@ are currently available on the system use *66-intree*(1) tool.
started when you use the *66-all*(1) tool.
*-D*
Disables _tree_. The strict opposite of the *-E* option.
Disables _tree_. The exact opposite of the *-E* option.
*-R*
Deletes _tree_. Can not be *undone*. This will completely remove the given
......@@ -115,7 +115,7 @@ for any regular user.
## WHEN ENABLING A SERVICE
By enabling a service its corresponding frontend service file is parsed and the
result written to a sub directory of the trees path called *servicedirs/svc* for
result written to a sub directory of the tree's path called *servicedirs/svc* for
_classic_ services and *servicedirs/db/source* for _bundle_ or _atomic_ services.
As an example for root the resulting files would, by default, be found at
......
......@@ -10,11 +10,15 @@
# DESCRIPTION
*66-update* is a program that is normally used very rarely: when the
66 package is upgraded or downgraded, some services are currently managed,
different tree as declared and the inner format has changed. This program transitions
a complete tree and a live directory using a database with the old 66 format (the one being replaced)
so that it uses a database with the new 66 format and rebuild the tree.
*66-update* is a program that should be used rarely. At upgrade/downgrade
time, the inner file format used to retrieve informations of tree,service
database currently in use, can differ between two versions. In this case,
service databases and trees need to be rebuild to match the new format.
The 66-update program makes a complete transition of trees and the live
directory using a old 66 format (the one being replaced) with the new 66 format.
The goal is to ensure a smooth transition between different versions of 66
without needing a reboot.
# OPTIONS
......@@ -23,10 +27,10 @@ so that it uses a database with the new 66 format and rebuild the tree.
*-v* _verbosity_
Increases/decreases the verbosity of the command.++
*1* : (Default) Only print error messages.++
*2* : Also print warning messages.++
*3* : Also print tracing messages.++
*4* : Also print debugging messages.
*1* : (Default) Only prints error messages.++
*2* : Also prints warning messages.++
*3* : Also prints tracing messages.++
*4* : Also prints debugging messages.
*-c*
enable colorization
......@@ -37,29 +41,32 @@ so that it uses a database with the new 66 format and rebuild the tree.
\--livedir=_live_ option to *./configure*. Should be under a writable
filesystem - likely a RAM filesystem.
If no _tree_ is given, all trees of the owner of the process will be processed.
If no _tree_ is given, all trees of the owner (root or user) of the
process will be processed. In the case of user owned trees *66-update*
must run separately for each user.
# TRANSITION PROCESS
It determines if the tree is already initialized. In such case, it
make a copy of the current database on a temporary directory and
switch the database to it.
makes a copy of the current database on a temporary directory and
switches the database to it.
It saves the current state of the tree (current,enabled,...).
It destroys the tree with *66-tree -R* command.
It creates the tree with *66-tree -n(cEa)* command, options depending of the saved state.
It creates the tree with *66-tree -n(cEa)* command, reproducing the options
of the saved state.
It enables the service(s) previously declared on the _tree_.
It switch the current database to the newly created by the enable process.
It switches the current database to the newly created database by the enable process.
At the end of the process, the tree and the live state has not changed. Services already is use
are not stopped or restarted during the transition process and match exactly the same state
before and after the process.
It try to be safe as possible and exit 111 is a problem occurs. In any case
It tries to be safe as possible and exit 111 is a problem occurs. In any case
on upgrade/downgrade time, 66 tools will not work properly if the transition
is not made smoothly even by the sysadmin itself. So, We prefer to cratch instead of
is not made smoothly even by the sysadmin itself. So, we prefer to crash instead of
leaving an inconsistent state and let the sysadmin correct the things.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment