README: update and add README.org alongside README

README

@@ -4,8 +4,7 @@
                                 ________
 
 
-A POSIX sh system-supervisor meant to take away the complexity of
-today's alternatives
+
 
 
 Rationale
@@ -103,7 +102,7 @@ SVCTL
 
 
 Switching from Runit
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
   If you want to switch from runit to sysmgr all you need to do is to
   run this following command
@@ -117,3 +116,32 @@ Switching from Runit
   |     cp "$service/run" "/var/sysmgr/${service##*/}"
   | done
   `----
+
+
+Utilities
+=========
+
+  `utils' directory is for non-essential tools that can be used
+  alongside `sysmgr'.
+
+
+sysmgr-needs
+~~~~~~~~~~~~
+
+  `sysmgr-needs' waits for the given service/s to start up. It was
+  inspired by the [Life without systemd] section of the [Busybox
+  Homepage] which mentions a `/bin/need' script that waits for a
+  file/directory/socket to exist.
+
+  You can incorporate this tool in your service scripts like this
+
+  ,----
+  | #!/bin/sh
+  | sysmgr-needs dbus || exit 1
+  | exec NetworkManager -n >/dev/null 2>&1
+  `----
+
+
+[Life without systemd] https://www.busybox.net/kill_it_with_fire.txt
+
+[Busybox Homepage] https://www.busybox.net

README.org

@@ -0,0 +1,113 @@
+#+TITLE: SYSMGR
+#+OPTIONS: num:nil toc:nil author:nil
+
+* Table of Contents                                            :TOC:noexport:
+- [[#rationale][Rationale]]
+- [[#overview][Overview]]
+  - [[#usage][Usage]]
+  - [[#current-functions][Current Functions]]
+  - [[#switching-from-runit][Switching from Runit]]
+- [[#utilities][Utilities]]
+  - [[#sysmgr-needs][sysmgr-needs]]
+
+* Rationale
+
+System-supervision is often seen as the most complicated
+part of managing a system. This is in part due to projects
+like [[https://github.com/systemd/systemd][systemd]] and [[https://wiki.gentoo.org/wiki/Project:OpenRC][OpenRC]]. However, those projects add some
+unnecessary fancy stuff and code complexity. systemd is not 
+even portable outside of Linux. System-supervision does not
+have to be this complicated.
+
+[[https://smarden.org/runit][Runit]] is a good alternative for system-supervision. However
+it is still too complex, and uses C, which brings me to the
+main point of this.
+
+A user should not be running some magic commands while not
+having an idea of what they are doing. A program that is just
+running some shell script should not be some complicated C
+program. It can just be managed from another shell process, a
+program that just makes use of basic UNIX utilities that exist
+on almost every system.
+
+* Overview
+
+SYSMGR is a POSIX-compliant shell program. It reads the service
+scripts from the given SYSDIR (which is =/var/sysmgr= by default)
+and executes them asynchronously via RUNSYSV. While exiting
+it sends a hangup signal to all RUNSYSSV processes.
+
+** Usage
+
+Add your service scripts to =/var/sysmgr=. An example service
+script would be (for ssh daemon):
+
+#+BEGIN_SRC sh
+#!/bin/sh
+exec /usr/bin/sshd -D
+#+END_SRC
+
+You can then run sysmgr to start your services.
+
+** Current Functions
+
+*** RUNSYSSV
+
+RUNSYSSV executes the system service and expects for signals.
+During this state it periodically checks to make sure its
+given service is still alive. If it is not alive RUNSYSSV removes
+its run directory (given that there is no lockfile inside) and
+exits.
+
+It is not meant to be run by the user, but there wouldn't be
+any issues with it either. You can run a service by doing
+=runsyssv /path/to/service= and it will run that service script
+given that there isn't any service with the same name on the
+run directory. You can specify a different =RUNDIR= if that
+is the case.
+
+*** SVCTL
+
+SVCTL is the function with which the user interacts with SYSMGR.
+The user will do a =svctl <command> <service-name>=. It currently
+has useful but limited options. These are,
++ start :: Removes the run directory for the service so that it can be started.
++ restart :: Sends a SIGTERM to the service and starts it back again.
++ stop :: Sends a SIGTERM to the service and adds a lockfile to its run directory, so that it is not restarted.
++ kill :: Sends a SIGKILL to the service and adds a lockfile to its run directory, so that it is not restarted.
++ up/down :: Same as start/stop
++ once :: Start the service and add a lockfile to its run directory, so that it is not restarted.
++ stat/status :: Check if the service is running or not
+
+** Switching from Runit
+
+If you want to switch from runit to sysmgr all you need to do is
+to run this following command
+
+#+BEGIN_SRC sh
+# Create the directory if you haven't yet
+mkdir -p /var/sysmgr
+
+# Copy your run scripts to /var/sysmgr
+for service in /var/service/* ; do
+    cp "$service/run" "/var/sysmgr/${service##*/}"
+done
+#+END_SRC
+* Utilities
+
+=utils= directory is for non-essential tools that can be used alongside
+=sysmgr=.
+
+** sysmgr-needs
+
+=sysmgr-needs= waits for the given service/s to start up. It was inspired
+by the [[https://www.busybox.net/kill_it_with_fire.txt][Life without systemd]] section of the [[https://www.busybox.net][Busybox Homepage]] which mentions
+a =/bin/need= script that waits for a file/directory/socket to exist.
+
+You can incorporate this tool in your service scripts like this
+
+#+BEGIN_SRC sh
+#!/bin/sh
+sysmgr-needs dbus || exit 1
+exec NetworkManager -n >/dev/null 2>&1
+#+END_SRC