changeset 315:9c5b76df4f9d

Begin manual pages for the "fjail" command
author Franz Glasner <fzglas.hg@dom66.de>
date Thu, 24 Nov 2022 09:37:57 +0100
parents 90c512baf109
children dc3ac7fc06ea
files docs/conf.py docs/man/index8.rst docs/man/man8/fjail.rst docs/man/man8/local-bsdtools.rst pkg-plist sbin/check-ports.bak
diffstat 6 files changed, 426 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/docs/conf.py	Thu Nov 24 02:03:58 2022 +0100
+++ b/docs/conf.py	Thu Nov 24 09:37:57 2022 +0100
@@ -72,6 +72,15 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ("man/man8/local-bsdtools", "local-bsdtools", 'FreeBSD administration helper tools v%s' % release, [author], 8),
+    ("man/man8/fjail", "fjail", "Management of Jails", [author], 8),
+    #("man/man8/fjail-configure", "fjail", "Basic Configuration of Jails", [author], 8),
+    #("man/man8/fjail-copy", "fjail-copy", "Recursively copy ZFS datasets including all properties", [author], 8),
+    #("man/man8/fjail-datasets", "fjail-datasets", "Create a new tree of ZFS datasets that will encompass a jail", [author], 8),
+    #("man/man8/fjail-hostid", "fjail-hostid", "Compute a proposal for a new BSD Host UUID and ID", [author], 8),
+    #("man/man8/fjail-mount", "fjail-mount", "Recursively mount a ZFS dataset and its children", [author], 8),
+    #("man/man8/fjail-populate", "fjail-populate", "Populate a directory with content from a FreeBSD base.txz", [author], 8),
+    #("man/man8/fjail-privs", "fjail-privs", "Adjust some privileges within a mounted jail", [author], 8),    
+    #("man/man8/fjail-umount", "fjail-umount", "Recursively unmount a ZFS datasets and its children", [author], 8),
     ("man/man8/ftjail", "ftjail", "Management of Thin Jails", [author], 8),
     ("man/man8/ftjail-build-etcupdate-current-tmpl", "ftjail-build-etcupdate-current-tmpl", "Build a \"current\" tree suitable for the default and extract mode of \"etcupdate\"", [author], 8),    
     ("man/man8/ftjail-copy-skel", "ftjail-copy-skel", "Recursively copy skeleton contents", [author], 8),
--- a/docs/man/index8.rst	Thu Nov 24 02:03:58 2022 +0100
+++ b/docs/man/index8.rst	Thu Nov 24 09:37:57 2022 +0100
@@ -9,6 +9,7 @@
 .. toctree::
 
    man8/local-bsdtools
+   man8/fjail
    man8/ftjail
    man8/ftjail-build-etcupdate-current-tmpl
    man8/ftjail-copy-skel
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/man/man8/fjail.rst	Thu Nov 24 09:37:57 2022 +0100
@@ -0,0 +1,69 @@
+.. -*- coding: utf-8; indent-tabs-mode: nil; -*-
+
+ftjail
+======
+
+Synopsis
+--------
+
+**fjail -hV**
+
+**fjail subcommand**
+
+
+Description
+-----------
+
+Management tool for Jails: creation of ZFS dataset hierarchies, mount,
+population and configuration helpers.
+
+
+Subcommands
+-----------
+
+:manpage:`fjail-configure(8)`
+
+    Do some basic configuration of an already populated and mounted
+    jail
+
+:manpage:`fjail-copy(8)`
+
+    Recursively copy ZFS datasets including all properties
+
+:manpage:`fjail-datasets(8)`
+
+    Create a new tree of ZFS datasets that will encompass a jail
+
+:manpage:`fjail-hostid(8)`
+
+    Generate a proposal for a new BSD host UUID and ID
+
+:manpage:`fjail-mount(8)`
+
+    Recursively mount a ZFS dataset and its children
+
+:manpage:`fjail-populate(8)`
+
+    Populate a directory with content from a FreeBSD base.txz
+
+:manpage:`fjail-privs(8)`
+
+    Adjust some privileges within a mounted jail
+
+:manpage:`fjail-umount(8)`
+
+    Recursively unmount a ZFS datasets and its children
+
+
+Implementation Notes
+--------------------
+
+Some commands require ZFS as filesystem.
+
+Some commands are suitable for Thin Jails also.
+
+
+Environment
+-----------
+
+All environment variables that affect :command:`zfs` are effective also.
--- a/docs/man/man8/local-bsdtools.rst	Thu Nov 24 02:03:58 2022 +0100
+++ b/docs/man/man8/local-bsdtools.rst	Thu Nov 24 09:37:57 2022 +0100
@@ -14,6 +14,18 @@
 - :manpage:`bsmtp2dma(8)`
 - :manpage:`check-ports(8)`
 - :manpage:`fjail(8)`
+
+  * :manpage:`fjail-configure(8)`
+  * :manpage:`fjail-copy(8)`    
+  * :manpage:`fjail-datasets(8)`
+  * :manpage:`fjail-hostid(8)`
+  * :manpage:`fjail-mount(8)`
+  * :manpage:`fjail-populate(8)`
+  * :manpage:`fjail-privs(8)`
+  * :manpage:`fjail-umount(8)`
+
+:manpage:`fjail-copy(8)`
+    
 - :manpage:`ftjail(8)`
 
   * :manpage:`ftjail-build-etcupdate-current-tmpl(8)`  
--- a/pkg-plist	Thu Nov 24 02:03:58 2022 +0100
+++ b/pkg-plist	Thu Nov 24 09:37:57 2022 +0100
@@ -7,6 +7,7 @@
 sbin/fpkg
 sbin/fzfs
 %%DOCS%%man/man8/local-bsdtools.8.gz
+%%DOCS%%man/man8/fjail.8.gz
 %%DOCS%%man/man8/ftjail.8.gz
 %%DOCS%%man/man8/ftjail-build-etcupdate-current-tmpl.8.gz
 %%DOCS%%man/man8/ftjail-copy-skel.8.gz
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sbin/check-ports.bak	Thu Nov 24 09:37:57 2022 +0100
@@ -0,0 +1,334 @@
+#!/bin/sh
+# -*- indent-tabs-mode: nil; -*-
+# @(#)$HGid$
+#
+
+VERSION="@@VERSION@@"
+
+#
+# Configuration directory
+#
+: ${CONFIGDIR:=@@ETCDIR@@}
+
+#
+# Mapping configuration: installed package name -> original package name
+# Note: This is independent of any repo
+#
+: ${PACKAGE_MAPPING:=${CONFIGDIR}/package-mapping.conf}
+
+#
+# Local repository with non-public packages and/or ports with changed
+# OPTIONS (i.e. not using the defaults) or forks of official packages with
+# other package names
+#
+: ${LOCAL_REPO:=LocalRepo}
+
+#
+# Local repository with ports with default OPTIONS (i.e. unchanged)
+# but newer than the packages in the "FreeBSD" repository.
+# Some sort of a fast-track repository.
+#
+: ${LOCALBSDPORTS_REPO:=LocalBSDPorts}
+
+#
+# The official FreeBSD binary repository
+#
+: ${FREEBSD_REPO:=FreeBSD}
+
+#
+# Directly installed from ports
+#
+: ${PORTS_DIRECT_INSTALLED_REPO:=unknown-repository}
+
+#
+# For the workaround of the bug in pkg rquery -I
+#
+: ${PORTSDIR:=/usr/ports}
+: ${INDEXDIR:=${PORTSDIR}}
+: ${INDEXFILE:=@@INDEXFILE@@}
+
+
+get_remote_repo_versions() {
+    local _repo _data _rv
+
+    _repo=$1
+
+    _data=$(pkg version -U -R -r ${_repo} -v)
+    _rv=$?
+    eval remote_versions_${_repo}=\"\${_data}\"
+    return ${_rv}
+}
+
+get_remote_repo_data() {
+    local _repo _name _rversions _rfqp _rl _rdescr
+
+    _repo=$1
+    _name=$2
+
+    eval _rversions=\"\${remote_versions_${_repo}}\"
+    while read _rfqp _rl _rdescr ; do
+        if [ ${_rfqp%-*} = ${_name} ] ; then
+            eval remote_label_${_repo}=\"\${_rl}\"
+            eval remote_descr_${_repo}=\"\${_rdescr}\"
+            return 0
+        fi
+    done <<EOF884657
+${_rversions}
+EOF884657
+    eval remote_label_${_repo}=""
+    eval remote_descr_${_repo}=""
+    return 1
+}
+
+get_local_index_versions() {
+    local_index_versions=$(pkg version -I -v)
+}
+
+get_repo_for_installed_package() {
+    local _name _n _v _r
+
+    _name=$1
+
+    while read _n _v _r ; do
+        if [ ${_name} = ${_n} ] ; then
+            repository=${_r}
+            return 0
+        fi
+    done <<EOF223777
+${installed_data}
+EOF223777
+    return 1
+}
+
+get_immediate_index_version() {
+    local _package _line _fqpn _n _lines
+
+    _package=$1
+
+#    _val=$(pkg rquery -I "${_package}" | cut -f 1 -d '|')
+#    _rv=$?
+#    immediate_index_version=${_val##*-}
+#    return ${_rv}
+
+    if [ -r "${INDEXDIR}/${INDEXFILE}" ] ; then
+        #
+        # Note: Direct piping does not set immediate_index_version at return correctly
+        #       "_line" is set correctly and parsing works, but the return 0 seems to kill
+        #       some of the previous effects.
+        #
+        # "grep" does a fast pre-selection, reading, parsing and comparing is done for
+        # exact matching.
+        #
+        _lines=$(egrep '^'"${_package}" "${INDEXDIR}/${INDEXFILE}")
+        while read _line ; do
+            _fqpn="${_line%%|*}"
+            _n=${_fqpn%-*}
+	    if [ "${_package}" = "${_n}" ] ; then
+                immediate_index_version="${_fqpn##*-}"
+                return 0
+            fi
+        done <<EOF1334TGH1
+${_lines}
+EOF1334TGH1
+    fi
+
+    immediate_index_version=""
+    return 1
+}
+
+get_immediate_remote_repo_version() {
+    local _repo _name _version _rv
+
+    _repo=$1
+    _name=$2
+
+    _version=$(pkg rquery -U -r "${_repo}" '%v' "${_name}")
+    _rv=$?
+    eval immediate_remote_repo_version_${_repo}=\"\${_version}\"
+    return ${_rv}
+}
+
+assert_local_version() {
+    local _name _version _n _v _r
+
+    _name=$1
+    _version=$2
+
+    while read _n _v _r ; do
+        if [ ${_name} = ${_n} ] ; then
+            if [ ${_version} != ${_v} ] ; then
+                return 1
+            else
+                return 0
+            fi
+        fi
+    done <<EOF223
+${installed_data}
+EOF223
+    return 2
+}
+
+get_mapping() {
+    local _package _n _mapped
+
+    _package=$1
+
+    if [ -r "${PACKAGE_MAPPING}" ] ; then
+        while read _n _mapped ; do
+            if [ "${_n}" = "${_package}" ] ; then
+                mapped_package_name="${_mapped}"
+                return 0
+            fi
+        done < ${PACKAGE_MAPPING}
+    fi
+    mapped_package_name=""
+    return 1
+}
+
+print_title() {
+    local _package _repo
+
+    _package=$1
+    _repo=$2
+    if [ -z "${title_printed}" ] ; then
+        echo "${_package}    (${_repo})"
+        title_printed=yes
+    fi
+}
+
+
+alldata_flag=""
+alldata_flag_LocalBSDPorts=""
+alldata_flag_LocalRepo=""
+short_flag=""
+verbose_flag=""
+
+while getopts "VAasv" _opt ; do
+    case ${_opt} in
+	V)
+            echo "check-ports v${VERSION} (rv:@@HGREVISION@@)"
+            exit 0
+	    ;;
+        A)
+            # print for every package the status of all repositories
+            alldata_flag=1
+            alldata_flag_LocalBSDPorts=1
+            alldata_flag_LocalRepo=1
+            ;;
+        a)
+            # print the data of all repos that have the package
+            alldata_flag=1
+            ;;
+        s)
+            # "short" output: if installed from FreeBSD repo: don't
+            # report if only the index is newer
+            short_flag=1
+            ;;
+        v)
+            # print all titles and repo of every installed always
+            verbose_flag=1
+            ;;
+        \?)
+            exit 2
+            ;;
+        *)
+            echo "option handling failed" >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [ -n "${short_flag}" -a -n "${alldata_flag}" ]; then
+    echo "the -s option cannot be combined with -A or -a" >&2
+    exit 2
+fi
+
+installed_packages=$(pkg query '%n')
+installed_data="$(pkg query '%n %v %R' $installed_packages)"
+
+get_remote_repo_versions ${LOCAL_REPO}
+get_remote_repo_versions ${LOCALBSDPORTS_REPO}
+get_remote_repo_versions ${FREEBSD_REPO}
+get_local_index_versions
+
+while read lfqp llabel ldescr ; do
+    _installed_name=${lfqp%-*}
+    _installed_version=${lfqp##*-}
+    title_printed=""
+    get_repo_for_installed_package ${_installed_name}
+    get_mapping ${_installed_name}
+    if [ -n "${verbose_flag}" ] ; then
+        print_title "${lfqp}" "${repository}"
+    fi
+    if ! assert_local_version ${_installed_name} ${_installed_version} ; then
+        echo "Assertion failed: $lfqp ${_installed_name} ${_installed_version} ${llabel}" >&2
+        exit 1
+    fi
+    get_remote_repo_data ${LOCAL_REPO} ${_installed_name}
+    get_remote_repo_data ${LOCALBSDPORTS_REPO} ${_installed_name}
+    get_remote_repo_data ${FREEBSD_REPO} ${_installed_name}
+    _print_detail=""
+    if [ -n "${mapped_package_name}" ] ; then
+        _print_detail=1
+    fi
+    if [ \( -n "${alldata_flag}" \) ]; then
+        _print_detail=1
+    else
+        if [ -n "${short_flag}" ]; then
+            #
+            # NOTE: -s and -A/-a are incompatible: so "alldata_XXX" needs not
+            #       to be checked!
+            #
+            case "${repository}" in
+                "${FREEBSD_REPO}")
+                    if [ \( "${llabel}" != '<' -a "${llabel}" != '=' \) -o "${remote_label_FreeBSD}" != '=' -o "${remote_label_LocalRepo}" != '?' -o "${remote_label_LocalBSDPorts}" != '?' ]; then
+                        _print_detail=1
+                    fi
+                    ;;
+                "${LOCAL_REPO}")
+                    _print_detail=1
+                    ;;
+                "${LOCALBSDPORTS_REPO}")
+                    if [ "${llabel}" != '=' -o "${remote_label_FreeBSD}" != '>' -o "${remote_label_LocalRepo}" != '?' -o "${remote_label_LocalBSDPorts}" = '?' -o "${remote_label_LocalBSDPorts}" = '<' ]; then
+                        _print_detail=1
+                    fi
+                    ;;
+                "${PORTS_DIRECT_INSTALLED_REPO}")
+                    _print_detail=1
+                    ;;
+                *)
+                    echo "ERROR: unhandled repository: ${repository}" >&2
+                    exit 1
+                    ;;
+            esac
+        else
+            if [ \( \( "${llabel}" != '?' -a "${llabel}" != '=' \) -o \( "${remote_label_FreeBSD}" != '?' -a "${remote_label_FreeBSD}" != '=' \) -o \( "${remote_label_LocalBSDPorts}" != '?' -a "${remote_label_LocalBSDPorts}" != '=' \) -o \( "${remote_label_LocalRepo}" != '?' -a "${remote_label_LocalRepo}" != '=' \) \) -o \( "${repository}" = "${PORTS_DIRECT_INSTALLED_REPO}" \) ]; then
+                _print_detail=1
+            fi
+        fi
+    fi
+    if [ -n "${_print_detail}" ]; then
+        print_title "${lfqp}" "${repository}"
+        echo "   INDEX        : ${llabel} ${ldescr}"
+        echo "   FreeBSD      : ${remote_label_FreeBSD} ${remote_descr_FreeBSD}"
+        if [ \( -n "${alldata_flag_LocalBSDPorts}" \) -o \( "${remote_label_LocalBSDPorts}" != '?' \) ] ; then
+            echo "   LocalBSDPorts: ${remote_label_LocalBSDPorts} ${remote_descr_LocalBSDPorts}"
+        fi
+        if [ \( -n "${alldata_flag_LocalRepo}" \) -o \( "${remote_label_LocalRepo}" != '?' \) ] ; then
+            echo "   LocalRepo    : ${remote_label_LocalRepo} ${remote_descr_LocalRepo}"
+        fi
+        if [ -n "${mapped_package_name}" ] ; then
+	    echo "   ---> ${mapped_package_name}"
+            get_immediate_index_version "${mapped_package_name}"
+	    get_immediate_remote_repo_version ${LOCAL_REPO} ${mapped_package_name}
+            get_immediate_remote_repo_version ${LOCALBSDPORTS_REPO} ${mapped_package_name}
+            get_immediate_remote_repo_version ${FREEBSD_REPO} ${mapped_package_name}
+            echo "      INDEX        : ${immediate_index_version}"
+            echo "      FreeBSD      : ${immediate_remote_repo_version_FreeBSD}"
+	    echo "      LocalBSDPorts: ${immediate_remote_repo_version_LocalBSDPorts}"
+	    echo "      LocalRepo    : ${immediate_remote_repo_version_LocalRepo}"
+        fi
+    fi
+done <<EOF856661111299999
+${local_index_versions}
+EOF856661111299999