From e931f63592947807642ffdf78947fb133108d2df Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Mon, 27 Jan 2025 16:05:31 -0500 Subject: [PATCH] Add boilerplate product guide --- .github/workflows/docs.yaml | 78 +++++++++++ .gitignore | 9 +- CMakeLists.txt | 33 +++++ CODE_OF_CONDUCT.md | 4 +- CONTRIBUTING.md | 4 +- README.md | 21 ++- apply_license.sh | 60 ++++++++ apply_license.tmpl | 19 +++ product-guide/CMakeLists.txt | 101 ++++++++++++++ product-guide/docinfo.xml.in | 49 +++++++ product-guide/install_imgs.sh | 30 ++++ product-guide/manual.adoc | 256 ++++++++++++++++++++++++++++++++++ product-guide/pdf-opts.xsl | 10 ++ product-guide/xhtml-opts.xsl | 17 +++ 14 files changed, 684 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 CMakeLists.txt create mode 100755 apply_license.sh create mode 100644 apply_license.tmpl create mode 100644 product-guide/CMakeLists.txt create mode 100644 product-guide/docinfo.xml.in create mode 100755 product-guide/install_imgs.sh create mode 100644 product-guide/manual.adoc create mode 100644 product-guide/pdf-opts.xsl create mode 100644 product-guide/xhtml-opts.xsl diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..005a860 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,78 @@ +## +## Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics +## Laboratory LLC. +## +## This file is part of the Bundle Protocol Security Library (BSL). +## +## Licensed under the Apache License, Version 2.0 (the "License"); +## you may not use this file except in compliance with the License. +## You may obtain a copy of the License at +## http://www.apache.org/licenses/LICENSE-2.0 +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +## See the License for the specific language governing permissions and +## limitations under the License. +## +## This work was performed for the Jet Propulsion Laboratory, California +## Institute of Technology, sponsored by the United States Government under +## the prime contract 80NM0018D0004 between the Caltech and NASA under +## subcontract 1700763. +## + +name: Build documentation + +on: [push] + +jobs: + build: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - name: dependencies + run: | + sudo apt-get update && sudo apt-get install -y cmake make coreutils ruby asciidoctor graphviz inkscape dblatex docbook-xsl-ns xsltproc xmlstarlet + sudo gem install asciidoctor-diagram + - name: build + env: + DESTDIR: public + run: | + cmake -S . -B build + cmake --build build + cmake --install build + - uses: actions/upload-artifact@v4 + with: + name: docs + path: public + + deploy: + # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages + permissions: + contents: read + pages: write + id-token: write + # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. + # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. + concurrency: + group: "pages" + cancel-in-progress: false + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-24.04 + steps: + - uses: actions/download-artifact@v4 + with: + name: docs + path: public + - name: Setup Pages + uses: actions/configure-pages@v3 + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: public + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.gitignore b/.gitignore index b38035f..da355a7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,10 @@ # editor files *~ -*.bak +.#* +.project +.cproject + +# generated files +build +*/docinfo.xml +public diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..a52cebe --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,33 @@ +#[[ +Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics +Laboratory LLC. + +This file is part of the Bundle Protocol Security Library (BSL). + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +This work was performed for the Jet Propulsion Laboratory, California +Institute of Technology, sponsored by the United States Government under +the prime contract 80NM0018D0004 between the Caltech and NASA under +subcontract 1700763. +]] +cmake_minimum_required(VERSION 3.16) +# No compiler checks +project(bsl-docs LANGUAGES ) +set(CMAKE_INSTALL_PREFIX "") + +#add_subdirectory(user-guide) +add_subdirectory(product-guide) + +install( + FILES index.html + DESTINATION . +) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 663e610..6fc7d3d 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,8 +1,8 @@ + + + JHU/APL + + + + 2023-2024 + The Johns Hopkins University Applied Physics Laboratory LLC + + + License + +This document is part of the Asynchronous Network Management System (ANMS). + + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + + +This work was performed for the Jet Propulsion Laboratory, California +Institute of Technology, sponsored by the United States Government under +the prime contract 80NM0018D0004 between the Caltech and NASA under +subcontract 1658085. + + + + + Initial + 30 August 2023 + + Initial issue of document for ANMS v1.0.0 + + + + A + 28 August 2024 + + Updates for ANMS v1.1.0 + + + diff --git a/product-guide/install_imgs.sh b/product-guide/install_imgs.sh new file mode 100755 index 0000000..f315d5b --- /dev/null +++ b/product-guide/install_imgs.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +SRCDIR=$1 +OUTDIR=$2 +DBOOKFILE=$3 + +if [ -z "${DBOOKFILE}" ] +then + FILENAMES="" + for HTMLFILE in ${OUTDIR}/*.html + do + echo "Scanning ${HTMLFILE}" + THESENAMES=$(xmlstarlet sel -N xhtml=http://www.w3.org/1999/xhtml -t -v '//xhtml:img/@src' -n "${HTMLFILE}") + FILENAMES="${FILENAMES} ${THESENAMES}" + done +else + FILENAMES=$(xmlstarlet sel -N db=http://docbook.org/ns/docbook -t -v '//db:imagedata/@fileref' -n "${DBOOKFILE}") +fi + +for FN in ${FILENAMES} +do + SRCFN="${SRCDIR}/${FN}" + if [ ! -f "${SRCFN}" ] + then + continue + fi + + DSTFN="${OUTDIR}/${FN}" + echo "Install to ${DSTFN}" + install -Dp -m644 "${SRCFN}" "${DSTFN}" +done diff --git a/product-guide/manual.adoc b/product-guide/manual.adoc new file mode 100644 index 0000000..3b98668 --- /dev/null +++ b/product-guide/manual.adoc @@ -0,0 +1,256 @@ +//// +Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics +Laboratory LLC. + +This file is part of the Bundle Protocol Security Library (BSL). + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +This work was performed for the Jet Propulsion Laboratory, California +Institute of Technology, sponsored by the United States Government under +the prime contract 80NM0018D0004 between the Caltech and NASA under +subcontract 1700763. +//// += Bundle Protocol Security Library (BSL) Product Guide +:doctype: book +:backend: docbook5 +:docinfo: shared +:toc: + + +[preface] +== Introduction + +This Product Guide provides architectural and maintenance details about the Bundle Protocol Security Library (BSL), which is part of the NASA Advanced Multi-Mission Operations System (AMMOS) suite of tools. + +=== Identification + +[%header,width=75%,cols=2*] +|=== +|Property +|Value + +|Configuration ID (CI) +|681.4 + +|Element +|Mission Control System (MCS) + +|Program Set +|Bundle Protocol Security Library (BSL) + +|Version +|1.0 +|=== + +=== Scope + +This document describes technical details about the BSL installation, upgrade, monitoring, and maintenance. +For details about the application programming interface (API) and workflows of the BSL see the <>. + +[glossary] +=== Terminology + +[glossary] +Bundle Protocol (BP):: +The overlay network protocol used to transport BPSec blocks and target blocks between nodes. +BP Agent (BPA):: +The instantiation of a BP node with a unique administrative Endpoint ID. +BP Endpoint:: +The source or destination of a BP bundle, identified by a BP Endpoint ID (EID). +BP Endpoint ID (EID):: +The identifier of a BP Endpoint; names the source and destination for a BP bundle. +Host:: +A single node on the network and a single instance of an operating system. +One host can have many interfaces and many IP addresses, but only one canonical host name. +JavaScript Object Notation (JSON):: +TBD + + +=== References + +.Applicable JPL Rules Documents +[%header,width=100%,cols="<.<3,>.<1"] +|=== +|Title +|Document Number + +|Software Development[[jpl-sd,SD]] +|57653 rev 10 + +|=== + + +.Applicable MGSS Documents +[%header,width=100%,cols="<.<3,>.<1"] +|=== +|Title +|Document Number + +|MGSS Implementation and Maintenance Task Requirements[[mimtar,MIMTaR]] +|DOC-001455 rev G + +|BSL Architecture Description Document[[bsl-add,BSL ADD]] +|DOC-005089 + +|BSL Software Requirements Document[[bsl-srd,BSL SRD]] +|DOC-TBD + +|BSL Software Interface Specification[[bsl-sis,BSL SIS]] +|DOC-TBD + +|BSL User Guide[[bsl-user-guide,BSL User Guide]] +|DOC-TBD + +|=== + +.Applicable Other Documents +[%header,width=100%,cols="<.<3,>.<1"] +|=== +|Title +|Reference + +|Using SELinux[[rhel9-selinux]] +|https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/pdf/using_selinux/red_hat_enterprise_linux-9-using_selinux-en-us.pdf[rhel9-selinux] + +|BSL Source[[bsl-source]] +|https://github.com/NASA-AMMOS/BSL[bsl-source] + +|BSL Document Source[[bsl-docs]] +|https://github.com/NASA-AMMOS/BSL-docs[bsl-docs] + +|=== + + +[#sec-arch] +== BSL Architecture + +TBD + + +[#sec-proc] +== Procedures + +This chapter includes specific procedures related to managing an BSL deployment. + + +[#sec-proc-build] +=== Building + +The BSL source is composed of a top-level repository `BSL` <> and a number of submodule repositories; all of them are required for building the BSL. + +. The top-level checkout can be done with: ++ +---- +git clone --recursive --branch https://github.com/NASA-AMMOS/BSL.git +---- +. Optional: switching to a different tag or branch can be done with the sequence: ++ +---- +git checkout +git submodule update --init --recursive +---- +. More TBD + + +[#sec-proc-install] +=== Installation + +TBD + + +[#sec-proc-upgrade] +=== Upgrading + +Because the BSL is deployed in an RPM package form, the normal operating system tools and procedures for dealing with software library upgrading apply to the BSL. +The BSL provides SOVERSION information in its libraries, so RPM management tools such as DNF which are cross-dependence-aware will ensure that the correct needed SOVERISON of the BSL is isntalled. + +Individual BSL releases may identify pre-upgrade or post-upgrade steps in their specific Release Description Document (RDD) which would agument this OS-standard procedure. + + +=== Monitoring + +The BSL itself, as a software library, does not directly make use of any logging mechanism. + +TBD + + +[#sec-proc-mon-selinux] +==== SELinux Audit Events + +The procedures in this section are a summary of more detail provided in Chapter 5 of the RedHat <> document. + +By default, the `setroubleshootd` service is running, which intercepts SELinux audit events + +To observe the system audit log in a formatted way run: +---- +sudo sealert -l '*' +---- + +Some SELinux denials are marked as "don't audit" which suppresses normal audit logging when they occur. +They are often associated with network access requests which would flood an audit log if they happen often and repeatedly. +To enable logging of `dontaudit` events run: +---- +sudo semanage dontaudit off +---- + + +[#sec-checkout] +=== Checkout Procedures + +The BSL packaging procedure includes built unit tests within the `bsl-test` RPM package which allows executing unit tests on the BSL library after build time on any other host. + +TBD + + +[#sec-support] +== Product Support + +There are two levels of support for the BSL: troubleshooting by a system administrator, which is detailed in <>, and upstream support via the BSL public GitHub project, accessible as described in <>. +Attempts to troubleshoot should be made before submitting issue tickets to the upstream project. + +[#sec-troubleshooting] +=== Troubleshooting + +==== Installation + +This section covers issues that can occur during installation (see <>) of the BSL. + +TBD + +==== Operations + +This section covers issues that can occur after successful installation (see <>) and checkout (see <>) of the BSL. + +==== SELinux Blocked Behavior + +TBD + +==== FIPS-140 Blocked Behavior + +TBD + +===== TBD + + +[#sec-contact] +=== Contacting or Contributing + +The BSL is hosted on a GitHub repository <> with submodule references to several other repositories. +There is a https://github.com/NASA-AMMOS/anms/blob/main/CONTRIBUTING.md[`CONTRIBUTING.md`] document in the BSL repository which describes detailed procedures for submitting tickets to identify defects and suggest enhancements. + +Separate from the source for the BSL proper, the BSL Product Guide and User Guide are hosted on a GitHub repository <>, with its own https://github.com/NASA-AMMOS/anms-docs/blob/main/CONTRIBUTING.md[`CONTRIBUTING.md`] document for submitting tickets about either the Product Guide or User Guide. + +While the GitHub repositories are the primary means by which users should submit detailed tickets, other inquiries can be made directly via email to the the support address mailto:dtnma-support@jhuapl.edu[,BSL Support]. + + +[index] +== Index diff --git a/product-guide/pdf-opts.xsl b/product-guide/pdf-opts.xsl new file mode 100644 index 0000000..11b7d80 --- /dev/null +++ b/product-guide/pdf-opts.xsl @@ -0,0 +1,10 @@ + + + 0 + 1 + 2 + + none + 0 + 0 + diff --git a/product-guide/xhtml-opts.xsl b/product-guide/xhtml-opts.xsl new file mode 100644 index 0000000..3d8735e --- /dev/null +++ b/product-guide/xhtml-opts.xsl @@ -0,0 +1,17 @@ + + + + + + 0 + 1 + 1 + 2 + +book toc,title,figure,table,example,equation + + + none + 1 + 0 +