~mc-return/upstart/upstart.merge-reduce-scopes-of-various-variables

.. contents::

=============================
Testing Sessions with Upstart
=============================

Upstart now has support for two types of "sessions":

* user sessions

* chroots sessions

Such sessions are implemented by asociating a separate Upstart session
with every chroot environment and every non-privileged user.

The session support does not yet provide full tests (as would be run by
"``make check``"). This is mostly due to the complexity of automatically
testing some of the scenarios below.

This document attempts to outline the minimum set of tests that should
be performed to ensure that session support works as expected.

Assumptions
===========

You are running an Ubuntu or Debian system.

User Sessions
=============

User sessions can be minimally tested using the script provided::

  util/tests/test_user_sessions.sh

Notes:

- Run "``test_user_sessions.sh -h``" to understand what this script does.

- that this script needs to be run on a system where the version of
  ``/sbin/init`` has session support since the ``/sbin/init`` binary
  itself will be tested. For this reason, the script cannot be run as part
  of the "``make check``" run.

- The script will complain loudly if any of the tests fail and tell you
  how to raise a bug.

Chroot Sessions
===============

Setup
-----

#. Install a chroot environement (such as ``schroot(1)``) and configure it.
#. run, "``debootstrap(8)``" to install the same release as you are running into your chroot.
#. Create the following files *outside* your chroot.

   - ``/etc/init/foo.conf``::
     
       start on wibble
       
       script
         exec 2>>/tmp/foo.$$.log
         set -x
         echo "foo: stat=`stat /`" 
         echo "foo: env=`env`"
         sleep 999 
       end script

   - ``/etc/init/outside_chroot.conf``::

       start on A
          
       script
         exec 2>>/tmp/outside_chroot.$$.log
         set -x
         echo "in_chroot: stat=`stat /`" 
         echo "in_chroot: env=`env`"
         sleep 999 
       end script

#. Create following files inside chroot environment.

   - ``/path/to/chroot/etc/init/foo.conf``::

       start on wibble
          
       script
         exec 2>>/tmp/foo.$$.log
         set -x
         echo "foo: stat=`stat /`" 
         echo "foo: env=`env`" 
         sleep 999
       end script

   - ``/path/to/chroot/etc/init/in_chroot.conf``::

       start on A
        
       script
         exec 2>>/tmp/in_chroot.$$.log
         set -x
         echo "in_chroot: stat=`stat /`" 
         echo "in_chroot: env=`env`" 
         sleep 999
       end script

   
Run as non-``root`` with no chroot
----------------------------------

- ``initctl list``

  Ensure list is contents of ``/etc/init/``: the command below should
  return no output::

    cmp <(initctl list|awk '{print $1}'|sort -u) <(cd /etc/init && ls *.conf|cut -d: -f2-|sed 's/\.conf//g'|sort -u)

- ``initctl status cron``

  Should work.

- ``initctl show-config``

  Should work.

- ``initctl check-config``

  Should work.

- ``start foo``

  Should fail ("``initctl: Rejected send message``").

- ``stop cron``

  Should fail ("``initctl: Rejected send message``").

- ``restart cron``

  Should fail ("``initctl: Rejected send message``").

- ``initctl emit bar``

  Should fail ("``initctl: Rejected send message``").

Run as ``root`` with no chroot
------------------------------

- ``initctl list``

  Ensure list is contents of ``/etc/init/``: command below should return no output::

    cmp <(initctl list|awk '{print $1}'|sort -u) <(cd /etc/init && ls *.conf|cut -d: -f2-|sed 's/\.conf//g'|sort -u)

- ``initctl status outside_chroot``

  Should work.

- ``initctl status in_chroot``

  Should fail with message::

    initct: Unknown job: in_chroot

- ``initctl show-config``

  Should work.

- ``initctl check-config``

  Should work.

- ``start in_chroot``

  Should fail with message::

    initct: Unknown job: in_chroot

- ``start outside_chroot``

  Should work.

- ``stop in_chroot``

  Should fail with message::

    initct: Unknown job: in_chroot

- ``restart outside_chroot``

  Should work.

- ``stop outside_chroot``

  Should work.

- ``initctl emit wibble``

  - Ensure ``/etc/init/foo.conf`` runs by looking at the log and ensuring
    the inode for the stat of '``/``' is the same as running "``stat /``" on
    the command-line.

  * Ensure ``/path/to/chroot/etc/init/foo.conf`` does *NOT* run.

- ``initctl emit A``

  - Ensure ``/etc/init/outside_chroot.conf`` runs.

  - Ensure ``/path/to/chroot/etc/init/in_chroot.conf`` does *NOT* run.

Run as ``root`` inside a chroot
-------------------------------

- ``initctl list``

  Ensure list is contents of ``/path/to/chroot/etc/init/``: command below should return no output::

    cmp <(initctl list|awk '{print $1}'|sort -u) <(cd /etc/init && ls *.conf|cut -d: -f2-|sed 's/\.conf//g'|sort -u)

- ``initctl status in_chroot``

  Should work.

- ``initctl status outside_chroot``

  Should fail with message::

    initct: Unknown job: outside_chroot

- ``initctl show-config``

  Should work.

- ``initctl check-config``

  Should work.

- ``start outside_chroot``

  Should fail with message::

    initct: Unknown job: outside_chroot

- ``stop outside_chroot``

  Should fail with message::

    initct: Unknown job: outside_chroot

- ``start in_chroot``

  Should work.

- ``restart in_chroot``

  Should work.

- ``stop in_chroot``

  Should work.

- ``initctl emit wibble``

  - Ensure ``/path/to/chroot/etc/init/foo.conf`` runs by looking at the log and ensuring
    the inode for the stat of '``/``' is the same as running "``stat /``" on the command-line.

  - Ensure ``/etc/init/foo.conf`` does *NOT* run.

- ``initctl emit A``

  - Ensure ``/path/to/chroot/etc/init/in_chroot.conf`` runs.

  - Ensure ``/etc/init/outside_chroot.conf`` does *NOT* run.

Run as non-root inside a chroot
-------------------------------

Not supported.

Run with ``--no-sessions``
--------------------------

The "``--no-sessions``" option makes Upstart behave as it used to prior to
the introduction of session support.

#. Reboot system and specify "``--no-sessions``" on kernel command-line.

#. Ensure "``initctl list``" within a chroot displays the same list as
   "``initctl list``" run outside of any chroot environment.