[Initng-svn] r3235 - initng/trunk/doc
svn at initng.thinktux.net
svn at initng.thinktux.net
Wed Mar 8 01:37:09 CET 2006
Author: trigger
Date: Wed Mar 8 01:37:08 2006
New Revision: 3235
Modified:
initng/trunk/doc/iimanual.txt
initng/trunk/doc/imanual.txt
initng/trunk/doc/initng.txt
Log:
Apply the patch from #482
Modified: initng/trunk/doc/iimanual.txt
==============================================================================
--- initng/trunk/doc/iimanual.txt (original)
+++ initng/trunk/doc/iimanual.txt Wed Mar 8 01:37:08 2006
@@ -1,109 +1,126 @@
.ii MANUAL
-.ii files are distro agnostic init files. During the build process of initng,
-the distro specific .i files are generated by the install_process program.
+.ii files are distro agnostic init files. During the build process of
+initng, the distro specific .i files are generated by the install_process
+program.
You may see the install_process program as something like an C preprocessor.
-Basically the .ii files are copied line by line into the .i file.
-However there are special constructs that can be used to generate
-distro-specic code.
+Basically the .ii files are copied line by line into the .i file. However
+there are special constructs that can be used to generate distro-specic
+code.
These construts are:
-#exec blocks
-#ifd blocks
- at foo@ statements
+
+ #exec blocks
+
+ #ifd blocks
+
+ @foo@ statements
+
#exec BLOCKS:
-the exec blocks starts with an "#exec" line, and ends with an "#endexec" line.
-Everything between "#exec" and "#endexec" is executed as a shell script. The
-output of the shell script is copied into the .i file.
+
+the exec blocks starts with an "#exec" line, and ends with an "#endexec"
+line. Everything between "#exec" and "#endexec" is executed as a shell
+script. The output of the shell script is copied into the .i file.
Example:
-#exec
-echo foo
-#endexec
+
+ #exec
+ echo foo
+ #endexec
This will create the line "foo" in the .i file.
+
#ifd BLOCKS:
-An #ifd block starts with a "#ifd DISTRO" line, and ends with an "#endd" line.
-install_process will try to probe your distribution,and copy the contents of
-the Block into the i file if your distribution is contained in DISTRO.
+An #ifd block starts with a "#ifd DISTRO" line, and ends with an "#endd"
+line.
+
+install_process will try to probe your distribution and copy the contents of
+the Block into the .i file if your distribution is contained in DISTRO.
-There may be one ore more "#elsed" line inside the #ifd Block. Think of it as
-"else" or "else if" in C.
+There may be one ore more "#elsed" line inside the #ifd Block. Think of it
+as "else" or "else if" in C.
Let's explain by an example:
-#ifd gentoo
-foo
-#elsed debian ubuntu
-bar
-#elsed
-baz
-#endd
+ #ifd gentoo
+ foo
+ #elsed debian ubuntu
+ bar
+ #elsed
+ baz
+ #endd
This will produce the line "foo" on gentoo, "bar" on debian and ubuntu, and
"baz" on every other distro. There must be no "#elsed DISTRO" lines after an
"#elsed" line with no distro specifier.
+
+
@foo@ STATEMENTS:
You know this problem: udhcpc is installed in /sbin on one distro, and in
/usr/sbin in some other distro. Here the @foo@ statements kick in.
in its basic form, @foo@ will search the PATH for the executable foo, and if
-found, it will replace @foo@ with the path of the foo executable.
+found, it will replace @foo@ with the path of the foo executable.
-In addition to the users PATH, install_service will also search in /sbin,
-/usr/sbin and /usr/local/sbin. this will allow building initng by unpriviliged
-users, whose PATH usually does not contain these directorys.
-
-But what if no foo executable is found? (This might be the case if the package
-foo wasn't installed when the user built initng.) In this case,
-install_process will use a builtin default path ( /usr/sbin ), so if no foo
+In addition to the users PATH, install_service will also search in /sbin,
+/usr/sbin and /usr/local/sbin. this will allow building initng by
+unpriviliged users, whose PATH usually does not contain these directorys.
+
+But what if no foo executable is found? (This might be the case if the
+package foo wasn't installed when the user built initng.) In this case,
+install_process will use a builtin default path (/usr/sbin), so if no foo
executable is found, @foo@ will produce /usr/sbin/foo.
-This default path might not be sufficient dor all services, so you have
+This default path might not be sufficient for all services, so you have
several possibilities to change it.
-SOLUTION 1:
-Use #atdefpath. You can override the builtin default path
-/usr/sbin with it. if you place an "#atdefpath /usr/bin" line in the .ii file
-_before_ the @foo@ statement, this for example will override the default path
+
+#atdefpath:
+
+Use #atdefpath. You can override the builtin default path usr/sbin with it.
+If you place an "#atdefpath /usr/bin" line in the .ii file before_ the
+ at foo@ statement, this for example will override the default path
with /usr/bin.
Any subsequent #atdefpath lines will _override_ previous default paths.
-#atdefpath also supports a special feature called multi-line default paths. An
-example:
-
-#atdefpath /usr/bin:/bin:/usr/local/bin
+#atdefpath also supports a special feature called multi-line default paths.
+An example:
-daemon = @foo@
+ #atdefpath /usr/bin:/bin:/usr/local/bin
+ daemon = @foo@
If a foo executable is not found in the PATH, the "daemon = @foo@" line will
not generate one output line, but three:
-daemon = /usr/bin/foo
-daemon = /bin/foo
-daemon = /usr/local/bin/foo
-
-SOLUTION 2:
-Use an @/my/path/foo@ construct. install_service will at first
-look if /my/path/foo exits. if yes, this line is printed. if no, the PATH is
+ daemon = /usr/bin/foo
+ daemon = /bin/foo
+ daemon = /usr/local/bin/foo
+
+
+@/path/file@:
+
+If you use the @/my/path/foo@ construct, install_service will at first look
+/if my/path/foo exits. if yes, this line is printed. if no, the PATH is
searched for foo. If install_service can find it in the PATH, then it will
-produce a /usr/sbin/foo, if it was found eg. in /usr/sbin. If it also couldn't
-be found in the path, then /my/path/foo will be created. Any previous set
-default paths will be ignored.
-
- at foo:bar@ CONSTRUCTS:
-But when you code distro agnostic .ii files, You might also arrive at another
-problem: one distro names your daemon "dbus-deamon", while another has
-"dbus-daemon-1". to solve this, you can write a statement like:
-"@dbus-daemon:dbus-daemon-1@" . First, install_process will search your PATH
+produce a /usr/sbin/foo, if it was found eg. in /usr/sbin. If it also
+couldn't be found in the path, then /my/path/foo will be created. Any
+previous set default paths will be ignored.
+
+
+ at foo:bar@:
+
+But when you code distro agnostic .ii files, you might also arrive at
+another problem: one distro names your daemon "dbus-deamon", while another
+has "dbus-daemon-1". to solve this, you can write a statement like:
+"@dbus-daemon:dbus-daemon-1@". First, install_process will search your PATH
for dbus-daemon. If it can't find it, it will search the PATH for
dbus-daemon-1. If it also can't find dbus-daemon-1, it will fall back on
dbus-daemon (the first name specified), using the default path (either
@@ -112,5 +129,3 @@
Note that this might produce multiple output lines if you use an multi-line
default path, but it will only produce output from the _first_ element.
-
-
Modified: initng/trunk/doc/imanual.txt
==============================================================================
--- initng/trunk/doc/imanual.txt (original)
+++ initng/trunk/doc/imanual.txt Wed Mar 8 01:37:08 2006
@@ -1,335 +1,346 @@
What is a .i file?
-A .i file is a file that lets you start a service or program easily by using the ngc or ng-update commands.
+A .i file is a file that lets you start a service or program easily by using
+the ngc or ng-update commands.
+
+
Where are they located?
-The .i files are located in the /etc/initng directory or subdirectories such as /etc/initng/system or /etc/initng/daemon.
+The .i files are located in the /etc/initng directory or subdirectories such
+as /etc/initng/system or /etc/initng/daemon.
+
+
Why would I want to edit or make one of these files?
-Well the reason is simple what if you would like to have a program start on startup but currently there is no script for it. Or a program won't start yet there is a script so soon you will have the skills to edit and fix these files.
+Well the reason is simple what if you would like to have a program start on
+startup but currently there is no script for it. Or a program won't start
+yet there is a script so soon you will have the skills to edit and fix these
+files.
Notice: the file must end in .i or initng will not see it!
-Basic Syntax:
-# start SaTaN0rX
-there are different things: daemons and services.
-a service is something that is only run once and then terminates. examples
-are: mount something, set the hostname, bring the network up, ...
+What can you define in .i files?
+
+Two different things: daemons and services.
+
+* a service is something that is only run once and then terminates. examples
+ are: mount something, set the hostname, bring the network up, ...
-in contrary, a daemon is a programm thats being started and runs all the time.
-for example apache, cups, ...
+* in contrary, a daemon is a programm thats being started and runs all the
+ time. for example apache, cups, ...
-the first thing you need to do is to figure out what you want to write:
-an .i file for a service or a daemon?
+The first thing you need to do is to figure out what you want to write: an
+.i file for a service or a daemon?
-SERVICES:
-a service might look like this:
-service system/foo {
- need = system/initial system/mountfs;
- use = system/alsasound;
- exec start = /sbin/foo;
- exec_args start = bar baz;
-}
+How do I define a service ?
-i'll explain these lines.
-the first line says that this service requires system/initial and
+A service might look like this:
+
+ service system/foo {
+ need = system/initial system/mountfs;
+ use = system/alsasound;
+ exec start = /sbin/foo --bar --baz;
+ }
+
+The first line says that this service requires system/initial and
system/mountfs to be run before it can be started.
-the second line says that it should also wait for system/alsasound is also in
-the current runlevel, then it should also wait for system/alsasound. but if
-system/alsasound is NOT in the current runlevel, this line would be ignored.
-in contrary, if it would have said need = system/alsasound, then
-system/alsasound would also have been started even if it is not in the current
-runlevel.
-
-the third line gives the program to start, in this case /sbin/foo
-
-and the forth line, you may have guessed it, gives additional parameters that
-should be passed to /sbin/foo.
-
-ok, now can also have a service that does something on start and on shutdown.
-it would look like this:
-
-service system/foo {
- need = system/initial system/mountfs;
- use = system/alsasound;
- exec start = /sbin/foo;
- exec_args start = bar baz;
- exec stop = /sbin/foo;
- exec_args stop = qux quux;
-}
-
-here, the stop and stop_args lines have been added. pretty easy.
-but there are situations in which you can not use some simple program, but u
-need a shell script. one solution would be to write that shell script to a
-file, and have a line like "exec start = /path/to/my/script.sh". while i would
-suggest you to do that for really large scripts (>100 lines), it would be kind
-an overkill to do so for a script with 5 lines of code. so initng provides a
-possibility to include these scripts .i files. example:
-
-service system/foo {
- need = system/initial system/mountfs;
- use = system/alsasound;
- script start = {
- [ -f /etc/conf.d/foo.conf ] && source /etc/conf.d/foo.conf
- [ -z "$FOO" ] & FOO="bar baz"
- /sbin/foo $FOO
- };
-}
+The second line says that it should also wait for system/alsasound is also
+in the current runlevel, then it should also wait for system/alsasound. But
+if system/alsasound is NOT in the current runlevel, this line would be
+ignored. in contrary, if it would have said need = system/alsasound, then
+system/alsasound would also have been started even if it is not in the
+current runlevel.
+
+The third line gives the program to start, in this case /sbin/foo. It will
+be called with the parameters "--bar --baz".
+
+Ok, now can also have a service that does something on start and on
+shutdown. it would look like this:
+
+ service system/foo {
+ need = system/initial system/mountfs;
+ use = system/alsasound;
+ exec start = /sbin/foo --bar --baz;
+ exec stop = /sbin/foo -qux --quux;
+ }
+
+Here, the stop and stop_args lines have been added. pretty easy. But there
+are situations in which you can not use some simple program, but you need a
+shell script. One solution would be to write that shell script into a file,
+and have a line like "exec start = /path/to/my/script.sh". While i would
+suggest you to do that for really large scripts (>100 lines), it would be
+kind an overkill to do so for a script with 5 lines of code. So initng
+provides a possibility to include these scripts .i files. An example:
+
+ service system/foo {
+ need = system/initial system/mountfs;
+ use = system/alsasound;
+ script start = {
+ [ -f /etc/conf.d/foo.conf ] && source /etc/conf.d/foo.conf
+ [ -z "$FOO" ] & FOO="bar baz"
+ /sbin/foo $FOO
+ };
+ }
+
+Note that you could also have stop script-block that is executed on
+shutdown. this block would be named, you guessed it, script stop { }.
+
-note that you could also have stop script-block that is executed on shutdown.
-this block would be named, you guessed it, script stop { }.
-DAEMONS:
+How do I define a daemon?
-a basic daemon .i file might look like this:
-daemon daemon/vixie-cron {
+A basic daemon .i file might look like this:
+
+ daemon daemon/vixie-cron {
need = system/initial system/clock system/mountfs system/bootmisc;
- exec daemon = /usr/sbin/cron;
- exec_args daemon = -n;
-}
+ exec daemon = /usr/sbin/cron -n;
+ }
it starts with "daemon daemon/blah {", and has a "exec daemon =" line in it.
-the "exec daemon =" specifies the daemon executable.
+The "exec daemon =" specifies the daemon executable.
+
+A daemon doesn't have "exec start", "exec stop" or "exec_args stop"
+directives, but has just an "exec daemon" directive. All other directives
+are the same as with services.
+
-a daemon doesn't have "exec start", "exec_args start", "exec stop" or "exec_args stop" directives, but has a
-"exec daemon" and "exec_args daemon" directive. all other directives are the
-same as with services.
-initng will by default track what the daemons are doing, ie it will monitor if
-a daemon crashes, etc. unfotunately, some daemons have a bad habit: forking.
+How to handly forking daemons?
-when a daemon forks, it spawns a copy of itself with a new pid. then the
-father process, with the old pid, dies.
+initng will by default track what the daemons are doing, i.e. it will
+monitor if a daemon crashes, etc. Unfotunately, some daemons have a bad
+habit: forking.
-this has some advantages: if you start cron from your console, then you
-instantly will see the bash prompt again. thats why most daemons fork.
+When a daemon forks, it spawns a copy of itself with a new pid. Then the
+father process, with the old pid, dies.
-unfortunately, initng has up to now no possibility to know if a daemon spawns
-a child or not. initng will only notice that the father process dies, and
-thinks that the daemon died.
+This has some advantages: if you start cron from your console, then you
+instantly will see the bash prompt again. Thats why most daemons fork.
-fortunately most daemons have a commandline switch which makes them not
-forking. in the case of vixie-cron it is -n. consult your daemons manpage.
+Unfortunately, initng has up to now no possibility to know if a daemon
+spawns a child or not. initng will only notice that the father process dies,
+and thinks that the daemon died.
-in some cases, the daemon can't be prevented from forking, but it will write
-the pid of the child process in a file, called the pid-file. initng can also use
-the pid file to track the daemon. an example:
+Fortunately most daemons have a commandline switch which makes them not
+forking. In the case of vixie-cron it is "-n". Consult your daemons manpage.
-daemon daemon/ntpd {
- need = system/initial system/mountfs system/mountfs net/lo;
+Un some cases, the daemon can't be prevented from forking, but it will write
+the PID of the child process in a file, called the pid-file. initng can use
+the PID file to track the daemon. An example:
+
+ daemon daemon/ntpd {
+ need = system/bootmisc
require_network;
use = daemon/ntpdate;
- exec daemon = /usr/sbin/ntpd;
- exec_args daemon = -p /var/run/ntpd.pid;
+ exec daemon = /usr/sbin/ntpd -p /var/run/ntpd.pid;
pid_file = /var/run/ntpd.pid;
-}
-
+ forks;
+ }
-this daemon WILL fork, but it will write the pid of the doughter process in
+This daemon WILL fork, but it will write the PID of the doughter process in
/var/run/ntpd.pid. initng can also track this daemon.
-another thing you can see is the require_network directive. this will delay
+Another thing you can see is the require_network directive. This will delay
the starting of this daemon until a network device is set up.
In a very bad case, a deamon might provide neither a switch to disable
-forking, nor will it write the pid of the forked process to a pidfile.
-for this case, initng has the possibility to look for a process by its name,
-as shown in this example:
+forking, nor will it write the PID of the forked process to a pidfile. for
+this case, initng has the possibility to look for a process by its name, as
+shown in this example:
-daemon daemon/portmap {
- need = system/mountroot;
+ daemon daemon/portmap {
+ need = system/bootmisc;
require_network;
+ forks;
pid_of = portmap;
exec daemon = /sbin/portmap;
-}
+ }
-portmap will fork, and write no pidfile. when the father porcess dies,
-initng will look for an process named portmap, and if one exists, it will use
-it's pid.
+portmap will fork, but will write no pidfile. When the father porcess dies,
+initng will look for an process named "portmap", and if one exists, it will
+use it's PID.
+
+
+
+What fork tracking should I use?
+
+Always use this order:
-While this sounds pretty easy, this should be used as LAST option. always use
-this order:
1) try to prevent the daemon from forking at all
2) if 1) is not possible, try to use pid_file
3) only if 1) and 2) are not possible, use pid_of
+
+
+What should I
+
ok, what's the buzz when you need some shell script to bring up the daemon?
-have a look at this example:
+Have a look at this example:
-daemon daemon/acpid {
- need = system/mountfs system/modules;
- use = system/discover system/coldplug;
+ daemon daemon/oidentd {
+ need = system/initial system/mountroot;
+ env OIDENT_OPTIONS=;
+ env OIDENT_USER=nobody;
+ env OIDENT_GROUP=nogroup;
+ env_file = /etc/default/oidentd;
+ require_network;
script daemon = {
+ if [ "${OIDENT_BEHIND_PROXY}" = "yes" ]
+ then
+ # If we have a default router, then allow it to proxy auth requests to us
+ GATEWAY=`netstat -nr | /usr/bin/awk'/^0.0.0.0/{print $2}'`
+ [ -n "${GATEWAY}" ] && OIDENT_OPTIONS="${OIDENT_OPTIONS} -P ${GATEWAY}"
+ fi
+ exec /usr/sbin/oidentd -i ${OIDENT_OPTIONS} -u ${OIDENT_USER} -g ${OIDENT_GROUP}
+ };
+ }
+As you can see you can also embedd an "script daemon = { script };" bash
+script in an .i file. But notice the "exec blah" statement. When you write
+"exec blah" in an bash script, the blah process will REPLACE the bash
+process, inheriting it's PID. This is necessary, so that initng can track
+your service. If you use pid_file, it is not absolutely necessary, but i'd
+suggest to do so.
- # As the name says. If the kernel supports modules, it'll try to load
- # the ones listed in "MODULES".
-
- .....
- # Check for ACPI support on kernel side
- [ -d /proc/acpi ] || exit 0
-
- # Include acpid defaults if available
- OPTIONS=""
- if [ -f /etc/default/acpid ] ; then
- . /etc/default/acpid
- fi
-
- [ -f /proc/modules ] && load_modules
-
-
- #for x in ac battery button fan ibm_acpi processor thermal video ; do
- # modprobe ${x} &> /dev/null
- #done
- exec /usr/sbin/acpid -f -c /etc/acpi/events
- };
-}
-i've shortened this a little bit :P
-as you can see you can also embedd an "script daemon = { script };" bash script in an .i
-file. but notice the "exec blah" statement. when you write "exec blah" in an
-bash script, the blah process will REPLACE the bash process, inheriting it's
-pid. this is necessary, so that initng can track your service. if you use
-pid_file, it is not absolutely necessary, but i'd suggest to do so.
+A note about other directives
+
+This should give an incomplete list of the other directives not explained
+above. You can get a list of most available options with a short description
+if you type "ngc -O".
+
+
+require_network:
+
+The start service or daemon is delayed until a network device other then lo
+is configured.
+
+
+last:
-DIRECTIVES:
-this should give an incomplete list of the other directives not explained
-above.
+The start service or daemon is delayed until all services and daemons, which
+are not last, are started.
-you can get a list of most available options with a short description if you type "ngc -O"
-require_network: the start service or daemon is delayed until a network device
- other then lo is configured.
+respawn:
-last: the start service or daemon is delayed until all services and daemons,
- which are not last, are started.
+If the daemon dies, it will be restarted.
-respawn: if the daemon dies, it will be restarted.
-NAMING THE .i FILE:
-when you name the .i file:
+How to name the .i file?
+
initng will look for the service "daemon/something" in
-"/etc/initng/daemon/smoething.i". so the exaple above has to go into
-"/etc/initng/daemon/acpid.i".
+"/etc/initng/daemon/something.i". So the example above has to go into
+"/etc/initng/daemon/oidentd.i".
+
+
-ADVANCED TOPICS:
+What are virtual blocks?
-have a look at daemon/agetty.i:
+Have a look at daemon/agetty.i:
-daemon daemon/agetty/tty1 {
+ daemon daemon/agetty/tty1 {
need = system/mountfs;
exec daemon = /sbin/agetty;
exec_args daemon = 38400 ${NAME};
respawn;
last;
-}
+ }
-daemon daemon/agetty/* {
+ daemon daemon/agetty/* {
need = system/mountfs;
exec daemon = /sbin/agetty;
exec_args daemon = 38400 ${NAME};
respawn;
-}
+ }
-virtual daemon/agetty {
- need = daemon/agetty/tty1 daemon/agetty/tty2 daemon/agetty/tty3 daemon/agetty/tty4 daemon/agetty/tty5 daemon/agetty/tty6;
- use = system/mountfs system/netmount;
-}
+ virtual daemon/agetty {
+ need = daemon/agetty/tty1 daemon/agetty/tty2 daemon/agetty/tty3 daemon/agetty/tty4 daemon/agetty/tty5 daemon/agetty/tty6;
+ use = system/mountfs system/netmount;
+ }
-#end of daemon/agetty.i
+The first block will define a daemon "daemon/agetty/tty1".
-the first block will define a daemon "daemon/agetty/tty1"
-
-the second block defines "daemon/agetty/*". now what is this? this Block
-contains a wildchar. when you tell initng to start daemon/agetty/foo, this
+The second block defines "daemon/agetty/*". Now what is this? This block
+contains a wildcard. When you tell initng to start daemon/agetty/foo, this
block will match it, so initng will use this block.
-You might notice the shell-style ${NAME} keyword. this keyword will be
-replaced by initng with the actual name of the service.
+You might notice the shell-style ${NAME} keyword. This keyword will be
+replaced by initng with the actual name of the service.
-NOTE: ${NAME} won't be "deamon/agetty/tty1" or the like, but it WILL be "tty1"
+NOTE: ${NAME} won't be "deamon/agetty/tty1" or the like, but it WILL be
+"tty1"
-This is usefull fr things like getty's, AND for things like network daemons
-that bind to individual interfaces. see daemon/<your favourite dhcp-client>
+This is usefull for things like getty's, AND for things like network daemons
+that bind to individual interfaces. See daemon/<your favourite dhcp-client>
for an example.
-the third block is an virtual. As you can see, there is neither a script, nor
-a exec statement in this block. So the virtual's don't do very much, the only
-thing they do is to depend on something, in this case in /daemon/agetty/tty1
-to tty6. This way, the user only needs to add daemon/agetty to his runlevel,
-and he gets all those agettys. after all agettys were started, daemon/agetty
-gets the status DONE.
-
-The order of the three blocks is of importance (it shuld not be important, but
-due to some bugs, it is).
-
-the first block should be in the file before the second one. When initng trys
-to find daemon/agetty/tty1 it will first find the first block, which matches,
-and executes this block.
-
-OTOH if the order of the block 1 and 2 was reversed, initng would first find the
-"daemon/agetty/*" block, which ALSO matches "deamon/agetty/tty1", and execute
-this block - this is not the desired behaviour.
-
-note that this is not the desired behaviour of initng, but rather a bug in
-initng, that was recently fixed, but, as devellopment goes on, it might
-re-appear ;).
-
-the third block shold be the last block for one reason: if the user adds
-daemon/agetty to his/her default runlevel, initng will look for this specific
-.i file, and parse it until it found daemon/agetty. it will stop after it has
-parsed the daemon/agetty{} block. any other block in the .i file up to this
-block will ALSO be parsed and added to initng's internal database. So, the
-other two blocks will already be parsed when they are needed.
-
-In this case, there should be no problem if the last block was the first one,
-BUT it might become a problem if the daemons are named differently.
-
-So in theory, the order would NOT matter, but in practice, the order might
-matter, due to some bugs. (this bugs should be fixed in 0.4.5, thou)
-
-TESTING YOUR .i FILE
-after you have written your .i file, it may still contain syntax errors and
-the like. so it's better not to shoot directly with "ngc -u daemon/mydaemon",
-but to do some test it first.
+The third block is a virtual block. As you can see, there is neither a
+script, nor a exec statement in this block. So the virtual's don't do very
+much, the only thing they do is to depend on something, in this case in
+/daemon/agetty/tty1 to tty6. This way, the user only needs to add
+daemon/agetty to his runlevel, and he gets all those agettys. After all
+agettys were started, daemon/agetty gets the status DONE.
+
+The order of the three blocks is of importance.
+
+The first block should be in the file before the second one. When initng
+trys to find daemon/agetty/tty1 it will first find the first block, which
+matches, and executes this block.
+
+If the order of the block 1 and 2 was reversed, initng would first find the
+"daemon/agetty/*" block, which ALSO matches "deamon/agetty/tty1", and
+execute this block - this is not the desired behaviour.
+
+The third block should be the last block for one reason: if the user adds
+daemon/agetty to his/her default runlevel, initng will look for this
+specific .i file, and parse it until it found daemon/agetty. It will stop
+after it has parsed the daemon/agetty{} block. Any other block in the .i
+file up to this block will ALSO be parsed and added to initng's internal
+database. So, the other two blocks will already be parsed when they are
+needed.
-The first step is to check for syntax errors. You can use the ./test_parser
-inside the devtool directory of the initng source distribution.
-after you have installed your .i file in the correct location ( usually
-/etc/initng/system/ or /etc/initng/daemon/ ), just run "./test_parser
-daemon/mydaemon". unfortunately, it's output is not very informative, so you
-have to check the exit status: "echo $?". if the exit staus is 2, an error has
-occured. otherwise, it is 0.
-The next thing you might try is to see if your .i file works pretty.
-i'd suggest you doing so by using initng in fake mode:
+How do I test my new .i file?
+
+After you have written your .i file, it may still contain syntax errors. So
+it's better not to shoot directly with "ngc -u daemon/mydaemon", but first
+do some tests with it.
-a) launch initng (as root). this will bring up another initng instance in the
-so called fake mode.
+The first step is to check for syntax errors. You can use the ./test_parser
+inside the devtool directory of the initng source distribution.
-b) comment all "need=" "require=" lines in your .i file
+After you have installed your .i file in the correct location (usually
+/etc/initng/system/ or /etc/initng/daemon/), just run "./test_parser
+daemon/mydaemon". If you don't wan't to dig throught it's output, you can
+check it's exit status with "echo $?". if the exit status is 2, an error has
+occured. otherwise, it is 0.
-c) do "ngdc -u daemon/mydaemon", and see what happens. if something doesn't
-work, and you need to change something in the .i file, just kill initng (the
-fake instance, of course!), edit your file and start with a)
+The next thing you might try is to see if your .i file works. I'd
+suggest you doing so by using initng in fake mode:
-d) if you are satisfied with your work, kill the fake instance, uncomment the
-"need=" and "require=" statements, and do "ngc -u daemon/mydaemon"
+a) launch initng (as root). this will bring up another initng instance in
+ the so called fake mode.
-e) if possible share your .i file with us! either send it to the ML, post it
-in bugzilla, or talk to one of us in the irc!
+b) comment all "need=" "require=" lines in your .i file.
+c) do "ngdc -u daemon/mydaemon", and see what happens. If something doesn't
+ work, and you need to change something in the .i file, just kill initng
+ (the fake instance, of course!), edit your file and start with a).
+d) If you are satisfied with your work, kill the fake instance, uncomment
+ the "need=" and "require=" statements, and do "ngc -u daemon/mydaemon"
-To be continued ...
+e) If possible share your .i file with us! Either send it to the mailing
+ list, post it in bugzilla, or talk to one of us in the IRC!
Modified: initng/trunk/doc/initng.txt
==============================================================================
--- initng/trunk/doc/initng.txt (original)
+++ initng/trunk/doc/initng.txt Wed Mar 8 01:37:08 2006
@@ -1,204 +1,224 @@
An overview of initng:
-On boot, initng will be started as the first process (pid = 1) by the kernel.
-At first, initng will parse configuration files located in /etc/initng for
-critical information such as runlevel and service data. After that, all services
-required by the default runlevel will be started as soon as their dependencies
-are met, allowing services to run in parallel. This asynchronous execution can
-dramatically improve boot time by better utilizing the system resources
-(especially in the case of multiprocessor systems).
+On boot, initng will be started as the first process (PID 1) by the
+kernel. At first, initng will parse configuration files located in
+/etc/initng for critical information such as runlevel and service data.
+After that, all services required by the default runlevel will be started as
+soon as their dependencies are met, allowing services to run in parallel.
+This asynchronous execution can dramatically improve boot time by better
+utilizing the system resources (especially in the case of multiprocessor
+systems).
Features:
--Automatic restarting of services that crash
--Easy starting, stopping, listing services through ngc
--Easy adding/removing services from a runlevel through ng-update
--SPEED!
+* Automatic restarting of services that crash
+* Easy starting, stopping, listing services through ngc
+* Easy adding/removing services from a runlevel through ng-update
+* SPEED!
-1) Installing initng:
+
+
+Installing initng:
For those of you that would like to use portage:
-ACCEPT_KEYWORDS="~ARCH" emerge initng //Please note you need to replace ~ARCH with your architecture ex: ~x86 ~ppc and others
+ ACCEPT_KEYWORDS="~ARCH" emerge initng
-For those of you that have portage and would like to install the latest version:
+(Please note you need to replace ~ARCH with your architecture ex: ~x86 ~ppc and
+others).
-#emerge subversion || apt-get install subversion
-#svn checkout http://jw.dyndns.org/initng/svn/initng
-#cd initng
-#./autogen.sh
-#./configure
-#make install
-
-For the rest of you:
-
-# tar -zxvf initng*.tar.gz
-# cd initng*
-# ./configure
-# make install
+If you want the latest version and have subversion installed:
-Configuring Grub:
+ # svn checkout http://jw.dyndns.org/initng/svn/initng/trunk initng
+ # cd initng
+ # ./autogen.sh
+ # ./configure
+ # make install
+
+You can also install initng from the source
+
+ # tar -zxvf initng*.tar.gz
+ # cd initng*
+ # ./configure
+ # make install
-Basically all you need to do here is add "init=/sbin/initng" to the line that starts with "kernel"
-Example:
+
+Configuring Grub:
+
+Basically all you need to do here is add "init=/sbin/initng" to the line
+that starts with "kernel"
Before:
-title=Gentoo Linux 2.6.12
-root (hd0,0)
-kernel /kernel-2.6.12-2 root=/dev/hdc3
+ title=Gentoo Linux 2.6.12
+ root (hd0,0)
+ kernel /kernel-2.6.12-2 root=/dev/hdc3
After:
-title=Gentoo Linux 2.6.12
-root (hd0,0)
-kernel /kernel-2.6.12-2 root=/dev/hdc3 init=/sbin/initng
+ title=Gentoo Linux 2.6.12
+ root (hd0,0)
+ kernel /kernel-2.6.12-2 root=/dev/hdc3 init=/sbin/initng
+
+
Configuring Lilo:
ADD LATER
-2) Configuring/Using initng:
-First off you need to reboot your linux install inorder to do the following (Please remember to boot into the one that uses initng)
-On the first console you will notice that you cannot log in and that you see 100% (If you do not please don't panic)
-Now hit alt+F2 and proceed to login
+Configuring and using initng:
-If earlier you saw 100% complete then you are set and you can skip down to the section on X.org
+First off you need to reboot your linux install inorder to do the following
+(Please remember to boot into the one that uses initng). On the first
+console you will notice that you cannot log in and that you see 100% (If you
+do not please don't panic).
-If you did not:
+Now hit alt+F2 and proceed to login
-type
+If you didn't see 100%, then type
-#ngc -s |more
+ # ngc -s | less
-If you see anything that did not start up or has a waiting for dependency next to it please make note of it. Somethings are trivial and can just be removed (ex: keymaps and consolefont).
+If you see anything that did not start up or has a waiting for dependency
+next to it please make note of it. Somethings are trivial and can just be
+removed (ex: keymaps and consolefont).
To remove the failed application:
-# ng-update del failedapplication
-2-1) Configuring X.org:
+ # ng-update del failedapplication
-2-1-1) Mouse Troubles:
-As of this time /dev/mouse does not exist. Inorder to get around this please change the path the mouse is on in your xorg.conf file from /dev/mouse to /dev/psaux.
-Example:
-
-Before:
+Adding or removing services from a run level:
-Section "InputDevice"
- Identifier "Mouse1"
- Driver "mouse"
- Option "Protocol" "IMPS/2"
- Option "Device" "/dev/mouse"
- Option "ZAxisMapping" "4 5"
-EndSection
+First: Figure out the name of your service you can do this by looking
+through the /etc/initng folder (files ending in .i are services)
-After:
+To add a service to a runlevel:
-Section "InputDevice"
- Identifier "Mouse1"
- Driver "mouse"
- Option "Protocol" "IMPS/2"
- Option "Device" "/dev/psaux"
- Option "ZAxisMapping" "4 5"
-EndSection
+ ng-update add service runlevel
-2-1-2) Nvidia Troubles:
+Examples:
-At this point in time I have not been able to get the nvidia drivers that are in portage to work on initng. So the solution is to download the drivers from the nvidia website and install them.
+ # ng-update add daemon/sshd default
+ # ng-update add system/alsasound default
-Steps:
-# modprobe -r nvidia
-# sh NVIDIA*
-# modprobe nvidia
+To remove a service from a runlevel:
-After you have done those things you should just be able to start xorg by doing:
-# startx
+ ng-update del service runlevel
-3) Adding or removing services from a run level:
+The runlevel part is optional but if you leave it out it removes it from all
+the runlevels its on.
-First: Figure out the name of your service you can do this by looking through the /etc/initng folder (files ending in .i are services)
+Examples:
-3-1) To Add a service to a runlevel:
+ # ng-update del daemon/sshd
+ # ng-update del system/alsasound default
+ # ng-update del daemon/sshd
+ # ng-update del system/alsasound
-ng-update add service runlevel
-Examples:
-# ng-update add daemon/sshd default <- this adds the ssh daemon to the runlevel "default"
-# ng-update add system/alsasound default <- this adds alsasound to the runlevel "default"
+Starting or Stopping a service:
-3-2) To Remove a service from a runlevel:
+First: Figure out the name of your service you can do this by looking
+through the /etc/initng folder (files ending in .i are services)
-ng-update del service runlevel (the runlevel part is optional but if you leave it out it removes it from all the runlevels its on)
+Starting a service:
-Examples:
-# ng-update del daemon/sshd <- this removes the ssh daemon from the runlevel "default"
-# ng-update del system/alsasound default <- this removes alsasound from the runlevel "default"
-# ng-update del daemon/sshd <- this removes the ssh daemon from every runlevel it is on
-# ng-update del system/alsasound <- this removes alsasound from every runlevel it is on
+ ngc -u service
-4) Starting or Stopping a service:
+Example:
-First: Figure out the name of your service you can do this by looking through the /etc/initng folder (files ending in .i are services)
+ # ngc -u daemon/sshd
-4-1) Starting a service:
+Stopping a service:
-ngc -u service
+ ngc -d service
Example:
-ngc -u daemon/sshd
+ # ngc -d daemon/sshd
-4-2) Stopping a service:
-ngc -d service
-Example:
+Listing all services:
-ngc -d daemon/sshd
+This lets you list all the services that are running which is particularly
+useful for troubleshooting and such matters.
-5) A warm restart:
+ # ngc -s
-A warm restart is a feature in initng that lets you restart all of the services in a matter of seconds without actually rebooting the computer.
-Warm Restart:
-# ngc -x
+To flush service data:
-6) Listing all services:
+This lets you flush memory service data, and reload from disc.
-This lets you list all the services that are running which is particularly useful for troubleshooting and such matters.
+ ngc -r service
-Listing the services:
+Example:
-# ngc -s
+ # ngc -r daemon/sshd
-7) To flush service data:
-This lets you flush memory service data, and reload from disc.
-Reloading the service:
+Zapping a service
-ngc -r service
+This lets you kill a service especially if stopping it won't work
+
+ ngc -z service
Example:
-# ngc -r daemon/sshd
+ # ngc -z daemon/sshd
-8) Zapping a service
-This lets you kill a service especially if stopping it won't work
-Zapping the service:
+Troubleshooting
-ngc -z service
+Mouse problems with X.org:
-Example:
+As of this time /dev/mouse does not exist. Inorder to get around this please
+change the path the mouse is on in your xorg.conf file from /dev/mouse to
+/dev/psaux.
+
+Before:
+
+ Section "InputDevice"
+ Identifier "Mouse1"
+ Driver "mouse"
+ Option "Protocol" "IMPS/2"
+ Option "Device" "/dev/mouse"
+ Option "ZAxisMapping" "4 5"
+ EndSection
+
+After:
+
+ Section "InputDevice"
+ Identifier "Mouse1"
+ Driver "mouse"
+ Option "Protocol" "IMPS/2"
+ Option "Device" "/dev/psaux"
+ Option "ZAxisMapping" "4 5"
+ EndSection
+
+
+Nvidia Troubles:
+
+At this point in time I have not been able to get the nvidia drivers that
+are in portage to work on initng. So the solution is to download the drivers
+from the nvidia website and install them.
+
+ # modprobe -r nvidia
+ # sh NVIDIA*
+ # modprobe nvidia
+
+After you have done those things you should just be able to start xorg by
+doing:
-# ngc -z daemon/sshd
+ # startx
More information about the Initng-svn
mailing list