From 0dab321eb1b1fbc11758982c14aa88b356c1bc98 Mon Sep 17 00:00:00 2001 From: Jan Pokorny Date: Dec 20 2010 21:49:33 +0000 Subject: README: more complete, instructions tried out --- diff --git a/README b/README index 89babd8..729e461 100644 --- a/README +++ b/README @@ -22,66 +22,142 @@ You can get newest luci code using:: Prerequisities for successful build/installation/deployment: * python (2.6, 2.7 should be also fine) - * Cyrus SASL v2 libraries and header files + * Cyrus SASL v2 (2.1.22+) libraries and header files * to use bundled initscript, check the additional requirements in the SPEC file (mostly common utilities that are found everywhere) Any missing Python package might be installed with ``setuptools`` automatically -(and if even ``setuptools`` missing, ``ez_setup`` is there to handle it). +(if even ``setuptools`` is missing, ``ez_setup`` is there to handle it). -Following items describe the steps to get it running:: +Following items describe the steps to get it running (instructions contain some +example values that should be modified to fit the environment, needs etc.): -1. Go to the ``luci'' directory and edit ``pkg_prepare`` section in - ``setup.cfg`` according to your needs (using ``vim``, for instance):: +0. Make sure you are navigated to the directory containing this ``README``. + If you have just cloned luci from the git repository as shown above, + you may need to move here: - $ cd luci - $ vim setup.cfg + $ cd luci - Note: Following steps use default values in ``setup.cfg`` so if you have - changed anything there, you might have to modify commands accordingly. +1. Edit ``pkg_prepare`` section in ``setup.cfg`` according to your needs + (using ``vim``, for instance). The names of configuration items there + should be self-explainatory:: - Note: It also possible to define all these options directly as command-line - arguments prefixed with ``prepare_pkg'' which is on the whole appended - to ``install`` command (see ``python setup.py pkg_prepare --help``) + $ vim setup.cfg -2. Install ``luci`` using the ``setup.py`` script:: + Note: Following steps use default values in ``setup.cfg`` so if you have + changed anything there, you might have to modify commands + accordingly. - $ python setup.py install + Note: It is also possible to define (in an overriding manner) all these + options directly as command-line arguments preceded by + ``prepare_pkg'' which are as a whole appended to ``install`` command + in the step 2., see also ``python setup.py pkg_prepare --help``. -3. Have the base configuration file generated from implicit template:: +2. Install ``luci`` using the ``setup.py`` script which also includes + prior compilation of C extensions and some files preparation:: - $ paste make-config luci /var/lib/luci/etc/luci.ini + $ python setup.py install -4. Similarly, create the database used by ``luci``:: +3. Optionally, you can change the certificate configuration file, especially + you can fill concrete hostname or IP address under which the machine + running luci will be accessible by other computers in the network, which + will prevent some (not all, there is still a problem that the generated + certificate is self-signed) of the warnings about the certificate:: - $ paster setup-app /var/lib/luci/etc/luci.ini + $ vim /var/lib/luci/etc/cacert.config - Note: This step is fired automatically if you use initscript and database - file is missing. +4. Now, there are two ways how to continue... The easier way is to use + bundled initscript -- just run two immediately following commands and you + are ready, having luci started (at worst, some little tweaking required). + If you want "expert-mode" way, just skip them and continue starting with + point 3b. This way follows the sequence of commands effectively used in + the initscript, although initscript is more fine-tuned so refer to it + if something gets stuck. -5. Start the ``paste`` http(s) server...:: +4a. Edit configuration file that comes with initscript according to your needs + (``vim`` used as an example here again): - a) ...using bundled initscript (recommended, but may require some tweaks):: + $ vim /etc/sysconfig/luci - $ service luci start +5a. Start the ``paste`` http(s) server using bundled initscript:: - Note: Before the first run of this commands, its good to do following:: + $ service luci start - $ chkconfig --add luci + Note: Before the first run of this command, it is good to do following:: - b) ...directly (this should copy the initscript job, only its core shown):: + $ chkconfig --add luci - $ saslauthd -a pam - $ paster serve /var/lib/luci/etc/luci.ini +6a. Luci should be running, check respective address (echoed by initscript). + To stop it, use:: - Note: The former command should be replaced with equivalent (``MECH=pam`` - is presumed in respective configuration) if applicable:: + $ service luci stop - $ service start saslauthd +4b. To achieve the same as with 5a. but using direct commands, start with + generating base configuration file from implicit template:: -Please note that these steps does not cover everything -- initscript and maybe + $ paster make-config luci /var/lib/luci/etc/luci.ini + +5b. Similarly, create the database used by ``luci``:: + + $ paster setup-app /var/lib/luci/etc/luci.ini + + Note: If you use preconfigured ``pkg_prepare`` section in ``setup.cfg``, + don't forget to create ``/var/lib/luci/data`` first (missing parts + of paths like this are not created automatically unless you use + initscript). + +6b. Generate self-signed certificate for luci using originally installed + configuration file (installation location depends on ``certconfig`` value + in ``setup.cfg`` which is ``/var/lib/luci/etc/cacert.config`` by default):: + + $ export RANDFILE=$(mktemp -q cert_rnd.XXXXXX) + $ openssl req -new -x509 -nodes -sha1 \ + > -newkey rsa:2048 \ + > -config /var/lib/luci/etc/cacert.config \ + > -days 1825 \ + > -set_serial "$(/bin/date +%s)" \ + > -keyout /var/lib/luci/certs/host.pem \ + > -out /var/lib/luci/certs/host.pem + + Note: If you use preconfigured ``pkg_prepare`` section in ``setup.cfg``, + don't forget to create ``/var/lib/luci/certs`` first (missing parts + of paths like this are not created automatically unless you use + initscript). + + Note: Do not forget to set the permissions for generated certificate + (``/var/lib/luci/certs/host.pem`` was used in the example) such that + it is only accessible by the user which then effectively runs luci. + +7b. Compared to point 4a. from a straightforward "initscript" way, you have no + other way (unless you will find out how to use config. file that comes + with initscript directly from initscript) then to edit base configuration + file immediately (``/var/lib/luci/etc/luci.ini`` by default). Especially + if you have used another path for the output certificate in the step 6b., + this configuration item should be edited respectively:: + + $ vim /var/lib/luci/etc/luci.ini + +8b. Finally, start the SASL daemon and then ``paste`` http(s) server...:: + + $ saslauthd -a pam + $ paster serve /var/lib/luci/etc/luci.ini + + Note: The former command might be replaced with equivalent if applicable + (``MECH=pam`` in respective configuration) :: + + $ service start saslauthd + + Note: To run luci on background, refer to the ``--daemon'' option + for ``paster'' command. + +9b. Luci should be running, check respective address (can be found in + configuration file used such as ``/var/lib/luci/etc/luci.ini`` from + the example). To stop it, press Ctrl-C. + + +Please note that these steps do not cover everything -- initscript and maybe the SPEC file might give you a better idea.