Skip to content

Commit

Permalink
Documentation cleanups etc. (rebase against cb3845c0)
Browse files Browse the repository at this point in the history
Added Debian packaging helper script
  • Loading branch information
rwpenney committed Sep 23, 2022
1 parent e631e0d commit 8aebafa
Show file tree
Hide file tree
Showing 16 changed files with 261 additions and 166 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ cm-*.so
config.h
config.log
config.status
debian/*-debtx
debian/patches/docfiles-pathnames.patch
delegates.h
doxygen.conf
Expand Down
72 changes: 36 additions & 36 deletions INSTALL → INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ and these can be installed using normal package-management tools. In general,
this is by far the easiest method of installing cryptmount. For example,
on Debian or Ubuntu systems, one can simply run

# sudo apt-get install cryptmount
sudo apt-get install cryptmount


Manual compilation
Expand All @@ -31,10 +31,10 @@ you want to customize some of its features, then this may require additional
packages to be available, and should be driven by the "configure" script.

If the configure script is missing, for example if working with a clone of
cryptmount's GitHub repository (https://github.com/rwpenney/cryptmount),
cryptmount's [GitHub repository](https://github.com/rwpenney/cryptmount),
then you may need to set up autoconf (version 2.61 or later), and run

# aclocal; autoconf; automake -a -c -i
aclocal; autoconf; automake -a -c -i


Dependencies
Expand All @@ -59,7 +59,7 @@ You will also need to ensure that your system has support for the
loopback and device-mapper devices, which may require loading
of kernel modules when you first use cryptmount, e.g.

# sudo modprobe -a loop dm-crypt
sudo modprobe -a loop dm-crypt

This is automatically performed on system reboot by setup scripts
supplied with cryptmount.
Expand All @@ -73,47 +73,47 @@ key libraries and header files needed by cryptmount, and allow customization
of the directory locations where cryptmount will be installed.
Typically, one can simply run:

# ./configure
./configure

although additional command-line options can also be supplied, such as:

--prefix=/usr
--prefix=/usr
# To install beneath /usr rather than /usr/local

--sysconfdir=/etc/cryptmount
--sysconfdir=/etc/cryptmount
# To specify the directory where the "cmtab" will be stored

--disable-luks
--disable-luks
# Turn-off support for LUKS encrypted containers

--with-systemd
--with-systemd
# Use systemd boot-up configuration, rather than sysvinit

A full list of options can be obtained by running

# ./configure --help
./configure --help


Compilation and installation
----------------------------

If "configure" has run successfully (generating a "config.h" file),
If "configure" has run successfully (generating a `config.h` file),
it should now be sufficient to run:

# make
# sudo make install
make
sudo make install

This should install both the cryptmount and cryptmount-setup executables,
This should install both the `cryptmount` and `cryptmount-setup` executables,
together with manual pages and an empty filesystem configuration file. Running

# sudo cryptmount-setup
sudo cryptmount-setup

will allow interactive creation of a basic encrypted filesystem
(using LUKS, if available). More sophisticated scenarios can be handled
by manual editing of the "cmtab", following the guidance in the manual pages:
by manual editing of the `cmtab`, following the guidance in the manual pages:

# man cryptmount
# man 5 cmtab
man cryptmount
man 5 cmtab

In outline, if not using the cryptmount-setup script, one can add an
entry to /etc/cryptmount/cmtab that describes the encrypted filesystem
Expand All @@ -127,12 +127,12 @@ that we want to create:

Thereafter, one can prepare the key-file and filing system as follows:

# sudo cryptmount --generate-key 32 crypt
# test -e /home/crypt.fs || sudo dd if=/dev/zero of=/home/crypt.fs bs=1M count=128
# sudo mkdir /mnt/crypt
# sudo cryptmount --prepare crypt
# sudo mke2fs -t ext4 /dev/mapper/crypt
# sudo cryptmount --release crypt
test -e /home/crypt.fs || sudo dd if=/dev/zero of=/home/crypt.fs bs=1M count=128
sudo mkdir /mnt/crypt
sudo cryptmount --generate-key 32 crypt
sudo cryptmount --prepare crypt
sudo mke2fs -t ext4 /dev/mapper/crypt
sudo cryptmount --release crypt


Configuring filesystems at system bootup
Expand All @@ -141,15 +141,15 @@ Configuring filesystems at system bootup
If you want to have encrypted filesystems setup at system boot-up,
this can be achieved using either 'systemd' or the supplied 'initscript'
program which is normally automatically installed as /etc/init.d/cryptmount .
Both of these mechanisms use the 'bootaction' parameter within
/etc/cryptmount/cmtab to adjust how each filesystem is
Both of these mechanisms use the `bootaction` parameter within
`/etc/cryptmount/cmtab` to adjust how each filesystem is
handled on system bootup.

If using the 'initscript' program, you may need to create symbolic links
from /etc/rc?.d to /etc/init.d/cryptmount (in a way that depends
If using the `initscript` program, you may need to create symbolic links
from /etc/rc?.d to `/etc/init.d/cryptmount` (in a way that depends
on the precise details of your distribution), with something like

# sudo update-rc.d cryptmount defaults 28
sudo update-rc.d cryptmount defaults 28

being suitable under Debian systems.

Expand All @@ -159,7 +159,7 @@ Common problems

When configuring the system devices needed to support an encrypted filesystem,
cryptmount will issue various requests through the device-mapper library.
Unfortunately, many of the error messages issued by that library
Unfortunately, some of the error messages issued by that library
(as of version 1.02) are not easy to interpret.

In situations where the device-mapper is compiled as a kernel module,
Expand All @@ -172,26 +172,26 @@ an error of the form
then this may indicate that the dm-mod kernel-module is not loaded.
This can be (temporarily) solved by issuing the command:

# sudo modprobe -a dm-mod dm-crypt
sudo modprobe -a dm-mod dm-crypt

In order to ensure that this happens automatically when you reboot,
you can add a line containing
"dm-mod" to /etc/modules, or add a line of the form
`dm-mod` to `/etc/modules`, or add a line of the form

modprobe -q -a dm-mod dm-crypt || true

to /etc/rc.local, or ensure that the cryptmount-startup scripts installed
to `/etc/rc.local`, or ensure that the cryptmount-startup scripts installed
in /etc/init.d are run on system startup (e.g. by installing suitable
symbolic-links from /etc/rc*.d).
symbolic-links from /etc/rc\*.d).

When setting up a new encrypted filing system, typically when issuing a
'cryptmount --prepare' command, you may receive an error message of the form
`cryptmount --prepare` command, you may receive an error message of the form

device-mapper ioctl cmd 9 failed: Invalid argument

which may mean that you have chosen a key-size that isn't supported by your
chosen cipher algorithm. You can get some information about suitable key-sizes
by checking the output from 'more /proc/crypto', and looking at the
by checking the output from `more /proc/crypto`, and looking at the
'min keysize' and 'max keysize' fields.)


Expand Down
2 changes: 1 addition & 1 deletion Makefile.am
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ endif
localedir=$(datadir)/locale
AM_CPPFLAGS += -DLOCALEDIR=\"$(localedir)\"
EXTRA_DIST = config.rpath mkinstalldirs cmtab.example \
README.md README.sshfs RELNOTES cryptmount.spec \
INSTALL.md README.md README.sshfs RELNOTES cryptmount.spec \
debian/changelog debian/control \
debian/copyright debian/docs \
debian/rules debian/cryptmount.lintian-overrides \
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ or raw disk partitions.
## Installation

To build cryptmount from source, please follow the instructions in
the file 'INSTALL' in the same directory as this file.
the file 'INSTALL.md' in the same directory as this file.

cryptmount has been tested (using the ["mudslinger"](testing/mudslinger.in) script
on a variety of GNU/Linux platforms including:
Expand Down Expand Up @@ -48,9 +48,9 @@ and which will be mounted beneath `/mnt/crypt`.

Such a filesystem could be initialized as follows:
```
cryptmount --generate-key 32 crypt
test -e /home/crypt.fs || dd if=/dev/zero of=/home/crypt.fs bs=1M count=128
mkdir /mnt/crypt
cryptmount --generate-key 32 crypt
cryptmount --prepare crypt
mke2fs -t ext4 /dev/mapper/crypt
cryptmount --release crypt
Expand Down
2 changes: 1 addition & 1 deletion armour-luks.c
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ static uid_t luks_patch_uid(const bound_tgtdefn_t* boundtgt)
if (stat(filename, &sbuff) == 0
&& S_ISREG(sbuff.st_mode)) {
if (setuid(geteuid()) != 0) {
fprintf(stderr, _("Failed to acquire privileges for LUKS container"));
fprintf(stderr, _("Failed to acquire privileges for LUKS container\n"));
}
}

Expand Down
3 changes: 1 addition & 2 deletions debian/control
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Package: cryptmount
Architecture: linux-any
Depends: ${shlibs:Depends}, ${misc:Depends}
Recommends: e2fsprogs (>= 1.42.12), udev
Suggests: openssl, dmsetup
Suggests: dmsetup
Description: Management of encrypted file systems
cryptmount is a utility for creating encrypted filesystems & swap partitions
and which allows an ordinary user to mount/unmount filesystems
Expand All @@ -31,4 +31,3 @@ Description: Management of encrypted file systems
* temporary filesystems can be setup via command-line,
for use in shell-scripts;
* transparent configuration of dm-crypt & loopback devices during mounting;
* access keys can optionally be made compatible with OpenSSL.
1 change: 1 addition & 0 deletions debian/docs
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
INSTALL.md
README.md
README.sshfs
RELNOTES
96 changes: 96 additions & 0 deletions debian/mkDebPkg
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
#!/bin/sh
# Construct debianized package for cryptmount
# RW Penney, June 2010

PACKAGE=cryptmount
VERSION=`sed -n 's/^AC_INIT[^,]*, *\([^,)]*\).*/\1/p' ../configure.ac`
PSEUDO_VERSION=""
UPSDIR=..

# $VERSION refers to the true version number associated with a *.tar.gz file
# $PSEUDO_VERSION is the stable release number for which a .deb should be generated

while [ $# -gt 0 ]; do
case "$1" in
-d|--upstream-dir)
UPSDIR="$2"
shift ;;
--pseudo-version)
PSEUDO_VERSION="$2"
shift ;;
-u|--upstream-version)
VERSION="$2"
shift ;;
-*)
echo "Unrecognized option \"$1\"" ;;
esac
shift
done

if [ -z "${PSEUDO_VERSION}" ]; then
PSEUDO_VERSION="${VERSION}"
fi

SRCPKG="${UPSDIR}/${PACKAGE}-${VERSION}.tar.gz"
if [ ! -r "${SRCPKG}" ]; then
echo "Upstream package ${SRCPKG} is not readable"
exit 1
fi

echo "Building Debian version ${PSEUDO_VERSION} from ${SRCPKG} ..."


DEBFILES="changelog control copyright \
docs cryptmount.lintian-overrides \
rules preinst postinst postrm watch \
patches/ source/ upstream/"

debtransform="s,/usr/local/etc/,/etc/,g; \
s,/usr/local/bin/,/usr/bin/,g; \
s,/usr/local/sbin/,/usr/sbin/,g"
TXFILES="INSTALL.md README.md README.sshfs cmtab.example"

TMPDIR=/tmp/cm-deb-${VERSION}
CURDIR=`pwd`
PKGDIR="${TMPDIR}/${PACKAGE}-${PSEUDO_VERSION}"


export QUILT_PATCHES=debian/patches
export QUILT_PATCH_OPTS="--reject-format=unified"
export QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"


test -d "${TMPDIR}" || mkdir "${TMPDIR}"
tar -C "${TMPDIR}" -zxf ${SRCPKG}
if [ "${PSEUDO_VERSION}" != "${VERSION}" ]; then
mv "${TMPDIR}/${PACKAGE}-${VERSION}" "${PKGDIR}"
fi

test -d patches || mkdir patches
(cd "${PKGDIR}"; test -d debian || mkdir debian)
if [ -n "${DEBFILES}" ]; then
tar -cf - ${DEBFILES} | \
tar -C "${PKGDIR}/debian" -xpf -
fi

cd "${PKGDIR}"
quilt new docfiles-pathnames.patch
for fl in ${TXFILES}; do
quilt add "${fl}"
sed "${debtransform}" ${fl} > ${fl}-debtx && mv ${fl}-debtx ${fl}
echo "Correct installation pathnames in documentation" | quilt header -r
done
quilt refresh


cd "${TMPDIR}"
cp ${SRCPKG} ${TMPDIR}/${PACKAGE}_${PSEUDO_VERSION}.orig.tar.gz
test -e ${SRCPKG}.sig && cp ${SRCPKG}.sig ${TMPDIR}/${PACKAGE}_${PSEUDO_VERSION}.orig.tar.gz.sig
dpkg-source -b ${TMPDIR}/${PACKAGE}-${PSEUDO_VERSION}

cd "${CURDIR}"
mv ${TMPDIR}/${PACKAGE}_* ./
rm -rf ${TMPDIR}

# vim: set ts=4 sw=4 et:
2 changes: 1 addition & 1 deletion debian/patches/install-example-cmtab.patch
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Move installation path of example configuration file to beneath /usr/share/doc
- ${INSTALL_PROGRAM_ENV} ${INSTALL_DATA} cmtab.example "${DESTDIR}${CM_SYSCONF_DIR}" ; \
fi
if test ! -f "${DESTDIR}${CM_SYSCONF_DIR}/cmtab" ; then \
echo -e "# ${CM_SYSCONF_DIR}/cmtab - encrypted filesystem information for cryptmount\n# try 'man 8 cryptmount' or 'man 5 cmtab' for more details\n" >> "${DESTDIR}${CM_SYSCONF_DIR}/cmtab"; \
echo -e "# ${CM_SYSCONF_DIR}/cmtab - encrypted filesystem information for cryptmount\n# try 'man 8 cryptmount' or 'man 5 cmtab' for more details\n# or refer to ${CM_SYSCONF_DIR}/cmtab.example\n" >> "${DESTDIR}${CM_SYSCONF_DIR}/cmtab"; \
fi
+ ${mkdir_p} "${DESTDIR}/usr/share/doc/cryptmount/examples"
+ ${INSTALL_PROGRAM_ENV} ${INSTALL_DATA} cmtab.example "${DESTDIR}/usr/share/doc/cryptmount/examples/cmtab"
Expand Down
Loading

0 comments on commit 8aebafa

Please sign in to comment.