From 3e211a5e779f0d8643a766f283e7dcf5826f1091 Mon Sep 17 00:00:00 2001 From: lars Date: Mon, 5 Sep 2005 16:44:40 +0000 Subject: [PATCH] new doc pages added cbox-build.sh splitted into itself and cbox-dev.sh --- cbox-build.sh | 107 +--------- cbox-dev.sh | 186 ++++++++++++++++++ .../doc/cryptobox/html/CryptoBoxDev.html | 17 +- .../html/CryptoBoxDevCustomBuild.html | 106 ++++++++++ .../html/CryptoBoxDevPreparation.html | 72 +++++++ .../cryptobox/html/CryptoBoxDevWorkFlow.html | 153 ++++++++++++++ tools/userdocexport.sh | 2 +- 7 files changed, 539 insertions(+), 104 deletions(-) create mode 100644 cbox-dev.sh create mode 100644 cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevCustomBuild.html create mode 100644 cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevPreparation.html create mode 100644 cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevWorkFlow.html diff --git a/cbox-build.sh b/cbox-build.sh index e69d672..bcd78ed 100755 --- a/cbox-build.sh +++ b/cbox-build.sh @@ -6,27 +6,19 @@ # dfsbuild - create the image directory with dfsbuild # config - apply cryptobox specific changes to the image directory # harden - remove unnecessary packages and disable developer features -# iso - create the iso image (out of the image directory) -# burn - tries to burn the the image on a cd-rw (maybe it works) -# -# development actions: -# chroot - run first tests in a chroot environment -# qemu - run the qemu emulation -# upload - copy your local files to tmpfs on a running cryptobox -# diff - compare tmpfs-files on a running cryptobox with the original -# merge - apply the diff to the local copy +# iso - create the iso image +# burn - burns the image on a cd-rw # # final action: # release - the same as "dfsbuild config harden iso" # # # problems of this script: -# - has to run as root, because dfsbuild, config, iso, chroot, devel -# and release need root privileges +# - has to run as root # - 'harden' is strangely integrated # # you may run this script with multiple arguments, e.g.: -# cb-build.sh dfsbuild config iso qemu +# cb-build.sh dfsbuild config iso # # the action "release" does what it says :) # (all developer's features like sshd, writable templates and @@ -111,20 +103,6 @@ function create_iso() } -function qemu_boot() -{ - # create a virtual harddisk image file - if [ ! -e "$HD_IMAGE" ] - then echo "Creating temporary harddisk image ..." - dd if=/dev/zero of="$HD_IMAGE" bs=1M count=20 - fi - echo "Starting qemu ..." - qemu -cdrom "$IMAGE_FILE" -m 96 -hda "$IMAGE_FILE" -boot d -n "$QEMU_IFUP_FILE" || true - # remove iptables rules - "$QEMU_IFUP_FILE" stop -} - - function configure_cb() { if [ ! -e "$IMAGE_DIR" ]; then @@ -168,58 +146,6 @@ function fetch_revision() } -function upload2box() -# upload local files to a development cryptobox -# this is necessary to use an "old" development cd with -# new code - this affects only the web-interface and the -# cbox-manage.sh-script (the boot behaviour stays the same) -# -# of course, only the directories that are mapped to tmpfs can -# be updated this way -{ - local DIRS="var/www usr/share/cryptobox usr/lib/cryptobox" - [ -e "$TMP_DIR" ] || mkdir -p "$TMP_DIR" - for a in $DIRS - do mkdir -p "$TMP_DIR/$a" - cp -r "$TEMPLATE_DIR/$a/." "$TMP_DIR/$a" - done - find "$TMP_DIR" -type d -name '\.svn' | while read a - do rm -rf "$a" - done - echo "Copying local files to the cryptobox ... " - if scp -F "$SSH_CONFIG_FILE" -rpq "$TMP_DIR/." cryptobox:/tmp/mirror - then echo "Set the base for future diffs to current state ..." - ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" "$DEV_FEATURES_SCRIPT" set_diff_base - else echo 'ERROR: copying failed!' - fi - rm -rf "$TMP_DIR" -} - - -function merge_from_box() -# merge a diff from a running development cryptobox into -# your local copy -{ - echo "Check for collisions ... (dry-run)" - if box_diff | patch --dry-run -p1 -d "$TEMPLATE_DIR" - then echo - echo "Applying diff ..." - box_diff | patch -p1 -d "$TEMPLATE_DIR" - echo - echo "Set the base for future diffs to current state ..." - ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" "$DEV_FEATURES_SCRIPT" set_diff_base - else echo "Merging will fail - do it manually!" - fi -} - - -# get the diff of a running cryptobox system between its current state -# and its original content -function box_diff() -{ - ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" "$DEV_FEATURES_SCRIPT" diff -} - function blanknburn_cdrw() { cdrecord -v dev=$CDWRITER blank=fast @@ -246,32 +172,9 @@ while [ $# -gt 0 ] iso ) create_iso ;; - qemu ) - qemu_boot - ;; - diff ) - # get a diff from a running development cryptobox - box_diff - ;; - merge ) - merge_from_box - ;; harden ) chroot "$IMAGE_DIR" "$CHROOT_START" /usr/lib/cryptobox/configure-cryptobox.sh secure ;; - upload ) - upload2box - ;; - chroot ) - if [ ! -x "$IMAGE_DIR/$CHROOT_START" ] - then echo "the chroot init script ("$IMAGE_DIR/$CHROOT_START") is not executable" - echo "maybe you should run '`basename $0` cb-config' first" - else chroot "$IMAGE_DIR" "$CHROOT_START" - fi - ;; - ssh ) - ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" - ;; burn ) blanknburn_cdrw ;; @@ -279,7 +182,7 @@ while [ $# -gt 0 ] $0 dfsbuild config harden iso ;; help|--help ) - echo "Syntax: `basename $0` ( release | dfsbuild | config | harden | iso | qemu | chroot | burn | upload | diff | merge | help )" + echo "Syntax: `basename $0` ( release | dfsbuild | config | harden | iso | burn | help )" echo " (you may specify more than one action)" echo ;; diff --git a/cbox-dev.sh b/cbox-dev.sh new file mode 100644 index 0000000..e5b5613 --- /dev/null +++ b/cbox-dev.sh @@ -0,0 +1,186 @@ +#!/bin/sh +# +# managing our work at the cryptobox +# +# development actions: +# chroot - run first tests in a chroot environment +# qemu - run the qemu emulation +# upload - copy your local files to tmpfs on a running cryptobox +# diff - compare tmpfs-files on a running cryptobox with the original +# merge - apply the diff to the local copy +# +# problems of this script: +# - chroot has to run as root +# + +set -ue + +# get the path of a configuration file - local configuration files +# supersede default files +# parameter: base name of the configuration file +function get_config_file() +{ + [ -e "$LOCALCONF_DIR/$1" ] && echo "$LOCALCONF_DIR/$1" && return 0 + [ -e "$DEFAULTCONF_DIR/$1" ] && echo "$DEFAULTCONF_DIR/$1" && return 0 + echo "configuration file ($1) not found!" >&2 + exit 1 +} + + +# the base directory of your local development files +ROOT_DIR=$(dirname "$0") + +# the template (default) configuration directory +DEFAULTCONF_DIR="$ROOT_DIR/etc-defaults.d" + +# your local configuration directory (existing files supersede the defaults) +LOCALCONF_DIR="$ROOT_DIR/etc-local.d" + +# local configuration directory - contains scripts to be executed after +# 'configure' +CUSTOM_CONFIGURE_DIR="$ROOT_DIR/configure-local.d" + +# template directory for cryptobox specific configuration +TEMPLATE_DIR="cbox-tree.d" + +# dfsbuild config +CONFIG=$(get_config_file dfs-cbox.conf) + +# the chroot-wrapper within the cryptobox +CHROOT_START="/usr/lib/cryptobox/chroot-start.sh" + +# qemu network configuration file +QEMU_IFUP_FILE=$(get_config_file qemu-ifup) + +# to connect to a development cryptobox with ssh +SSH_CONFIG_FILE=$(get_config_file ssh_config) + +# extract the hostname of the cryptobox from the ssh_config file +SSH_HOST=$(grep "^Host " "$SSH_CONFIG_FILE" | head -1 | sed 's/^Host *\(.*\)$/\1/') + + +############# include local configuration ############## + +if [ -e "$(get_config_file cbox-dev.conf)" ] + then source "$(get_config_file cbox-dev.conf)" + else echo "local cbox-dev.conf ($(get_config_file cbox-dev.conf)) does not exist!" >&2 + exit 1 + fi + +# image directory created by dfsbuild +# the BUILD_DIR is defined in the local cbox-dev.conf +IMAGE_DIR="$BUILD_DIR/image" + + +####################### functions ###################### + + +function qemu_boot() +{ + # create a virtual harddisk image file + if [ ! -e "$HD_IMAGE" ] + then echo "Creating temporary harddisk image ..." + dd if=/dev/zero of="$HD_IMAGE" bs=1M count=20 + fi + echo "Starting qemu ..." + qemu -cdrom "$IMAGE_FILE" -m 96 -hda "$IMAGE_FILE" -boot d -n "$QEMU_IFUP_FILE" || true + # remove iptables rules + "$QEMU_IFUP_FILE" stop +} + + +function upload2box() +# upload local files to a development cryptobox +# this is necessary to use an "old" development cd with +# new code - this affects only the web-interface and the +# cbox-manage.sh-script (the boot behaviour stays the same) +# +# of course, only the directories that are mapped to tmpfs can +# be updated this way +{ + local DIRS="var/www usr/share/cryptobox usr/lib/cryptobox" + [ -e "$TMP_DIR" ] || mkdir -p "$TMP_DIR" + for a in $DIRS + do mkdir -p "$TMP_DIR/$a" + cp -r "$TEMPLATE_DIR/$a/." "$TMP_DIR/$a" + done + find "$TMP_DIR" -type d -name '\.svn' | while read a + do rm -rf "$a" + done + echo "Copying local files to the cryptobox ... " + if scp -F "$SSH_CONFIG_FILE" -rpq "$TMP_DIR/." cryptobox:/tmp/mirror + then echo "Set the base for future diffs to current state ..." + ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" "$DEV_FEATURES_SCRIPT" set_diff_base + else echo 'ERROR: copying failed!' + fi + rm -rf "$TMP_DIR" +} + + +function merge_from_box() +# merge a diff from a running development cryptobox into +# your local copy +{ + echo "Check for collisions ... (dry-run)" + if box_diff | patch --dry-run -p1 -d "$TEMPLATE_DIR" + then echo + echo "Applying diff ..." + box_diff | patch -p1 -d "$TEMPLATE_DIR" + echo + echo "Set the base for future diffs to current state ..." + ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" "$DEV_FEATURES_SCRIPT" set_diff_base + else echo "Merging will fail - do it manually!" + fi +} + + +# get the diff of a running cryptobox system between its current state +# and its original content +function box_diff() +{ + ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" "$DEV_FEATURES_SCRIPT" diff +} + +############################# main ##################################### + +[ $# -eq 0 ] && echo "[`basename $0`] - no arguments supplied - maybe you want to use '--help'" + +ACTION=--help +[ $# -gt 0 ] && ACTION=$1 + +case "$1" in + diff ) + # get a diff from a running development cryptobox + box_diff + ;; + merge ) + merge_from_box + ;; + upload ) + upload2box + ;; + chroot ) + if [ ! -x "$IMAGE_DIR/$CHROOT_START" ] + then echo "the chroot init script ("$IMAGE_DIR/$CHROOT_START") is not executable" + echo "maybe you should run '`basename $0` cb-config' first" + else chroot "$IMAGE_DIR" "$CHROOT_START" + fi + ;; + qemu ) + qemu_boot + ;; + ssh ) + ssh -F "$SSH_CONFIG_FILE" "$SSH_HOST" + ;; + help|--help ) + echo "Syntax: `basename $0` ( qemu | chroot | upload | diff | merge | help )" + echo + ;; + * ) + echo -e "unknown action: $1" + echo + $0 help + exit 1 + ;; + esac + esac diff --git a/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDev.html b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDev.html index 8b9bd1f..ed6f3d9 100644 --- a/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDev.html +++ b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDev.html @@ -2,6 +2,10 @@
    +
  1. +Some more dev-pages +
    2. +
  2. Komponenten
      @@ -73,6 +77,17 @@

      +

      Some more dev-pages

      + + +

      Komponenten

      Eine CryptoBox CD wird in wenigen Schritten erstellt. Die Basisarbeit erledigt 'dfsbuild' und die genaue Konfiguration macht 'cbox-build'.

      @@ -345,7 +360,7 @@ CONFIG_TUN=m -

      last edited 2005-08-08 08:33:33 by

      +

      last edited 2005-09-05 16:19:53 by lars

      diff --git a/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevCustomBuild.html b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevCustomBuild.html new file mode 100644 index 0000000..49154df --- /dev/null +++ b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevCustomBuild.html @@ -0,0 +1,106 @@ + + +
        + +
      1. +Overview +
        2. + +
      2. +Settings +
          + +
        1. +dfsbuild settings +
          2. + +
        2. +CryptoBox development configuration +
          3. + +
        3. +SSH connection +
          4. + +
        4. +qemu network configuration +
          5. + +
        + +
        3. + +
      +

      +
      +

      +

      back to CryptoBoxDev

      + +

      Overview

      + +

      The following sections are useful, if you want to change the default settings of your personal CryptoBox development environment.

      +

      You should have completed the steps described in CryptoBoxDevPreparation.

      + +

      Settings

      + + +

      dfsbuild settings

      + +

      All settings for dfsbuild can be found in etc-defaults.d/dfs-cbox.conf.

      +

      If you want to change any of them, you should do the following:

      +
        +

      1. copy etc-defaults.d/dfs-cbox.conf file to etc-local.d/

        +
        2. +

      2. change etc-local.d/dfs-cbox.conf according to your needs

        +
        3. +
      +

      This allows you to use your own (personal) settings, without interfering with files under version control.

      + +

      CryptoBox development configuration

      + +

      Some settings regarding the building, configuring and validating of the CryptoBox can be found in etc-defaults.d/cbox-dev.conf.

      +

      If you want to change any of them, you should do the following:

      +
        +

      1. copy etc-defaults.d/cbox-dev.conf file to etc-local.d/

        +
        2. +

      2. change etc-local.d/cbox-dev.conf according to your needs

        +
        3. +
      + +

      SSH connection

      + +

      The file etc-defaults.d/ssh_config is used to establish a connection to a running CryptoBox system.

      +

      It can be necessary to change these settings, if:

      +
        +

      • you do not want to use the default IP for the CryptoBox

        +
        • +

      • or the CryptoBox is not within your local network.

        +
        • +
      +

      If you want to change some settings, you should do the following:

      +
        +

      1. copy etc-defaults.d/ssh_config file to etc-local.d/

        +
        2. +

      2. change etc-local.d/ssh_config according to your needs

        +
        3. +
      + +

      qemu network configuration

      + +

      The file etc-defauolts.d/qemu-ifup is used for the CryptoBox emulation with qemu. See man qemu for details.

      +

      If you want to change some settings, you should do the following:

      +
        +

      1. copy etc-defaults.d/qemu-ifup file to etc-local.d/

        +
        2. +

      2. change etc-local.d/qemu-ifup according to your needs

        +
        3. +
      + + + +

      last edited 2005-09-05 16:14:50 by lars

      + + + + + diff --git a/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevPreparation.html b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevPreparation.html new file mode 100644 index 0000000..60073eb --- /dev/null +++ b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevPreparation.html @@ -0,0 +1,72 @@ + + +
        + +
      1. +Software requirements +
        2. + +
      2. +Get the source +
        3. + +
      3. +First try +
        4. + +
      4. +Finished +
        5. + +
      +

      +
      +

      +

      back to CryptoBoxDev

      + +

      Software requirements

      + +

      We use [WWW] Debian as our development environment. This was a natural choice, as the CryptoBox-LiveCD is also based on Debian. Other distributions should work too, of course - [Acronym]YMMV.

      +

      required:

      + +

      recommended:

      + + +

      Get the source

      + +

      Download the latest release from our [WWW] subversion-Repository: +

      +
      +svn checkout https://svn.systemausfall.org/svn/cryptobox/trunk
      + +

      First try

      + +

      run ./cbox-build.sh release as root - hopefully, there should be no errors :)

      +

      Hint: This step will fail, if you did not install apt-cacher. See CryptoBoxDevCustomBuild for details on how to change build-configuration settings (in this case: mirror in dfs.cbox.conf).

      + +

      Finished

      + +

      Now you can start to pariticipate in the development of the CryptoBox or simply customize your own CryptoBox-LiveCD.

      +

      See CryptoBoxDevWorkFlow for details of how to use the developer's tools of the CryptoBox.

      +

      CryptoBoxDevCustomBuild shows some examples for local customizations of the CryptoBox.

      + + + +

      last edited 2005-09-05 13:50:51 by lars

      + + + + + diff --git a/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevWorkFlow.html b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevWorkFlow.html new file mode 100644 index 0000000..5b12da3 --- /dev/null +++ b/cbox-tree.d/usr/share/doc/cryptobox/html/CryptoBoxDevWorkFlow.html @@ -0,0 +1,153 @@ + + +
        + +
      1. +Preparations +
        2. + +
      2. +Create a CryptoBox-LiveCD - step by step +
          + +
        1. +Build the base system +
          2. + +
        2. +Configure the base image +
          3. + +
        3. +Remove development features +
          4. + +
        4. +Create an iso image +
          5. + +
        5. +Burn the CD +
          6. + +
        + +
      3. +Test the CryptoBox-LiveCD +
          + +
        1. +Chroot: quick & dirty tests +
          2. + +
        2. +Qemu: nearly complete emulation +
          3. + +
        + +
      4. +Debugging and merging +
          + +
        1. +Development on a running system +
          2. + +
        2. +Uploading a new release +
          3. + +
        + +
        5. + +
      +

      +
      +

      +

      back to CryptoBoxDev

      + +

      Preparations

      + +

      You should have completed the steps described in CryptoBoxDevPreparation.

      + +

      Create a CryptoBox-LiveCD - step by step

      + +

      The following steps can be executed in the order of their appearance.

      +

      Usually there is no need to repeat the whole process, after you changed some parts of the CryptoBox. Especially the first step (building of the base system with dfsbuild) may usually be skipped.

      +

      Every step of the building process must be executed as root.

      + +

      Build the base system

      + +

      Run ./cbox-build.sh dfsbuild to create the base system for the LiveCD.

      +

      The result can be found in _builddir/cd1/image.

      +

      If you do not want to use the [DebianPackage]apt-cacher to save bandwith and time, then you should modify the mirror-setting in dfs.cbox.conf (see CryptoBoxDevCustomBuild for details).

      + +

      Configure the base image

      + +

      Run ./cbox-build.sh config to copy the CryptoBox-specific files to the base image.

      +

      TODO: link to cbox-build.sh-manpage

      + +

      Remove development features

      + +

      The original base system, that was created by dfsbuild contains a lot packages and some scripts, that are only useful during development. You should remove them, as they case severe security implications.

      +

      To reduce the CryptoBox-LiveCD to the usable minimum for operational use, you should run ./cbox-build.sh harden.

      + +

      Create an iso image

      + +

      To burn a CryptoBox-LiveCD, you need an bootable iso9660-image.

      +

      Create the iso image with ./cbox-build.sh iso. The resulting file can be found at _builddir/cd1/cryptobox.iso.

      + +

      Burn the CD

      + +

      Do it manually: cdrecord -v dev=0,0,0 _builddir/cd1/cryptobox.iso (change the dev setting according to your setup).

      +

      Let the script do it for you: ./cbox-build.sh burn (maybe you have to change the CDWRITER setting in cbox-dev.conf - see CryptoBoxDevCustomBuild).

      +

      Of course, it is not wise to use CD-R media. Use CD-RW instead.

      + +

      Test the CryptoBox-LiveCD

      + +

      This section is only useful for developers, who want to improve or change the CryptoBox system.

      + +

      Chroot: quick & dirty tests

      + +

      If you modified the perl- or shell-scripts of the CryptoBox, then you can check for syntax errors by running them in a chroot environment. Be careful: you have access to all ressources of your computer, while you are working within a chroot environment - so you can easily repartition your real disk ...

      +

      To start a chroot environment, you can execute ./cbox-build.sh chroot.

      +

      For more intensive tests, you may use qemu (see below) or burn real LiveCDs - of course this would take much more time.

      + +

      Qemu: nearly complete emulation

      + +

      The processor emulator [WWW] qemu allows you test the CryptoBox in a virtual environment, that is completely separated from your real computer's resources. It is the tool of choice, if you do nat have a real computer around for testing.

      +

      Beware - there are some problems, when using qemu:

      +
        +

      • smbd does not start (segfault)

        +
        • +

      • ???

        +
        • +
      +

      To start a qemu emulation of the iso image, you may type: ./cbox-build.sh qemu.

      + +

      Debugging and merging

      + +

      This section is only useful for developers, who want to develop on a running CryptoBox system (emulated or real).

      +

      You may access the CryptoBox directly or you can use ssh to open a remote session (./cbox-build.sh ssh).

      + +

      Development on a running system

      + +

      When you run an emulation or test a real LiveCD, you may encounter problems and bugs. To test your fixes for these problems, it is convenient, to change the running test system. Afterwards you can merge these changes to your local development copy.

      +

      Type ./cbox-build.sh diff to see the changes, you made on the running CryptoBox system.

      +

      Type ./cbox-build.sh merge to merge these changes to your local working copy.

      + +

      Uploading a new release

      + +

      Alternatively you may also upload a new version of your local working copy to the running CryptoBox system.

      +

      Type ./cbox-build.sh upload - beware: all recent changes you made to the running CryptoBox system, are lost.

      + + + +

      last edited 2005-09-05 16:13:58 by lars

      + + + + + diff --git a/tools/userdocexport.sh b/tools/userdocexport.sh index e416ec9..ec53fb5 100755 --- a/tools/userdocexport.sh +++ b/tools/userdocexport.sh @@ -5,7 +5,7 @@ set -u ROOT_DIR="$(dirname $(dirname $0))" # retrieve these pages from the wiki -PAGES="CryptoBox CryptoBoxDev CryptoBoxKonzept CryptoBoxEn" +PAGES="CryptoBox CryptoBoxDev CryptoBoxKonzept CryptoBoxEn CryptoBoxDevPreparation CryptoBoxDevCustomBuild CryptoBoxDevWorkFlow" # base URL WIKI_HOST="https://systemausfall.org"