├── .github └── workflows │ ├── all.yaml │ ├── main.yaml │ └── stable.yaml ├── .gitignore ├── DISCLAIMER ├── LICENSE ├── Makefile ├── README.md ├── hunspell_dictionary_root_pages.txt ├── k8s ├── app │ ├── deploy-rootpages-main.yaml │ ├── deploy-rootpages-stable.yaml │ ├── ing-rootpages.yaml │ ├── svc-rootpages-main.yaml │ └── svc-rootpages-stable.yaml └── auth │ ├── ns-rootpages.yaml │ ├── role-github-actions.yaml │ ├── rolebinding-github-actions.yaml │ ├── sa-github-actions.yaml │ └── secret-sa-github-actions.yaml └── src ├── _static └── .gitignore ├── _templates └── .gitignore ├── administration ├── index.rst ├── init.rst ├── linux_kernel.rst ├── mail_servers.rst ├── operating_systems.rst ├── package_managers.rst └── performance_tuning.rst ├── automation ├── ansible.rst ├── index.rst └── puppet.rst ├── commands ├── clustering.rst ├── compression.rst ├── configuration_management.rst ├── firewalls.rst ├── hardware.rst ├── index.rst ├── openstack.rst ├── package_managers.rst ├── permissions.rst ├── phones.rst ├── security.rst ├── software_code_management.rst ├── storage.rst ├── template.rst ├── text_editors.rst └── virtualization.rst ├── computer_hardware ├── accessories.rst ├── desktops.rst ├── electrical_equipment.rst ├── graphics_cards.rst ├── index.rst ├── laptops.rst ├── monitors.rst ├── networking.rst ├── power_supply_units.rst ├── processors.rst ├── ram.rst ├── storage_devices.rst └── webcams.rst ├── conf.py ├── graphics ├── desktop.rst ├── drivers.rst ├── gaming.rst └── index.rst ├── http ├── clustering.rst ├── cms.rst ├── databases.rst ├── http_servers.rst └── index.rst ├── index.rst ├── networking ├── dns_servers.rst ├── firewalls.rst ├── index.rst └── linux.rst ├── observation ├── index.rst ├── logging.rst └── monitoring.rst ├── openstack ├── contributor.rst ├── index.rst ├── kolla.rst ├── openstack-ansible.rst ├── openstack.rst └── tripleo.rst ├── programming ├── c_and_c++.rst ├── devops.rst ├── go.rst ├── index.rst ├── machine_learning.rst ├── packaging.rst ├── python.rst ├── rust.rst └── shell.rst ├── public_clouds ├── amazon_web_services.rst ├── index.rst └── microsoft_azure.rst ├── security ├── authentication.rst ├── index.rst ├── linux_security.rst └── mandatory_access_control.rst ├── storage ├── backup_and_recovery.rst ├── bootloaders.rst ├── ceph.rst ├── file_systems.rst └── index.rst ├── template.rst ├── unix_distributions ├── android.rst ├── arch_linux.rst ├── asahi_linux.rst ├── chromium_os.rst ├── fedora.rst ├── index.rst ├── macos.rst ├── raspberry_pi_os.rst └── steamos.rst ├── virtualization ├── containers.rst ├── cpu_emulation.rst ├── index.rst ├── kubernetes_administration.rst ├── kubernetes_development.rst ├── kubernetes_security.rst ├── virtual_machines.rst └── wine.rst └── windows ├── display.rst ├── editions.rst ├── index.rst ├── performance_tuning.rst ├── security.rst ├── storage.rst └── virtualization.rst /.github/workflows/all.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | name: Build documentation 3 | on: 4 | push: 5 | # Build but do not publish for all development branches that may become pull requests. 6 | branches: 7 | - '*' 8 | - '!main' 9 | - '!stable' 10 | jobs: 11 | build: 12 | name: Build documentation 13 | runs-on: ubuntu-24.04 14 | steps: 15 | - uses: actions/checkout@v2 16 | - name: Change directory 17 | run: cd $GITHUB_WORKSPACE 18 | - name: Install Sphinx dependencies 19 | run: sudo apt-get update && sudo apt-get install -y python3-sphinx python3-sphinx-rtd-theme 20 | - name: Verify that the build works 21 | run: make html 22 | -------------------------------------------------------------------------------- /.github/workflows/main.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | name: Publish latest notes online 3 | on: 4 | push: 5 | branches: 6 | - main 7 | env: 8 | SA_GITHUB_ACTIONS_TOKEN: ${{ secrets.SA_GITHUB_ACTIONS_TOKEN }} 9 | jobs: 10 | build: 11 | name: Publish latest notes online 12 | runs-on: ubuntu-24.04 13 | steps: 14 | - uses: actions/checkout@v2 15 | - name: Change directory 16 | run: cd $GITHUB_WORKSPACE 17 | - name: Install Sphinx dependencies 18 | run: sudo apt-get update && sudo apt-get install -y python3-sphinx python3-sphinx-rtd-theme 19 | - name: Verify that the build works 20 | run: make html 21 | - name: Download 'kubectl' 22 | run: curl -LO 'https://storage.googleapis.com/kubernetes-release/release/v1.24.11/bin/linux/amd64/kubectl' && chmod +x ./kubectl 23 | - name: Force a rolling update of the deployment 24 | run: ./kubectl --insecure-skip-tls-verify --kubeconfig="/dev/null" --server=https://k8s.lukeshort.cloud:6443 --token=$SA_GITHUB_ACTIONS_TOKEN -n ns-rootpages patch deployment deploy-rootpages-main -p "{\"spec\":{\"template\":{\"metadata\":{\"annotations\":{\"date\":\"`date --utc --iso-8601=ns`\"}}}}}" 25 | -------------------------------------------------------------------------------- /.github/workflows/stable.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | name: Publish stable notes online 3 | on: 4 | push: 5 | branches: 6 | - stable 7 | env: 8 | SA_GITHUB_ACTIONS_TOKEN: ${{ secrets.SA_GITHUB_ACTIONS_TOKEN }} 9 | jobs: 10 | build: 11 | name: Publish stable notes online 12 | runs-on: ubuntu-24.04 13 | steps: 14 | - uses: actions/checkout@v2 15 | - name: Change directory 16 | run: cd $GITHUB_WORKSPACE 17 | - name: Download 'kubectl' 18 | run: curl -LO 'https://storage.googleapis.com/kubernetes-release/release/v1.24.11/bin/linux/amd64/kubectl' && chmod +x ./kubectl 19 | - name: Force a rolling update of the deployment 20 | run: ./kubectl --insecure-skip-tls-verify --kubeconfig="/dev/null" --server=https://k8s.lukeshort.cloud:6443 --token=$SA_GITHUB_ACTIONS_TOKEN -n ns-rootpages patch deployment deploy-rootpages-stable -p "{\"spec\":{\"template\":{\"metadata\":{\"annotations\":{\"date\":\"`date --utc --iso-8601=ns`\"}}}}}" 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | html/ 3 | build/ 4 | builddir/ 5 | locale/ 6 | locales/ 7 | *.retry 8 | -------------------------------------------------------------------------------- /DISCLAIMER: -------------------------------------------------------------------------------- 1 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 2 | 3 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 4 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = -n -W --keep-going 6 | SPHINXBUILD = sphinx-build 7 | SPHINXPROJ = RootPages 8 | SOURCEDIR = src 9 | BUILDDIR = build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Root Pages 2 | 3 | [![Build Status](https://github.com/LukeShortCloud/rootpages/actions/workflows/main.yaml/badge.svg)](https://github.com/LukeShortCloud/rootpages/actions/workflows/main.yaml) 4 | 5 | Root Pages is a collection of quick and easy-to-reference tutorials, examples, and guides primarily for Linux and other UNIX-like systems. The main goal of this project is to provide a more general purpose alternative to the "info" documents for System Administrators, Engineers, and Architects. Each page is a full guide to each topic. This makes it easy to navigate and search for content. 6 | 7 | All Root Pages are written in the reStructuredText (RST) markup language. Sphinx is used for building the documentation into ePub, HTML, PDF, and other common document formats. 8 | 9 | ## Website 10 | 11 | * Stable updates: https://rootpages.lukeshort.cloud/ 12 | * Latest development updates: https://rootpages.lukeshort.cloud/latest/ 13 | 14 | All commits to Root Pages are automatically tested via a GitHub Actions workflow. The latest successful build of the "main" branch is pushed to a Kubernetes cluster. Tags are published and a "stable" branch is updated quarterly. 15 | 16 | ## Install 17 | 18 | Sphinx is a Python package that is required to compile Root Pages into different document formats. It is provided by most operating systems' package manager. The official installation guide can be found [here](http://www.sphinx-doc.org/en/stable/install.html). 19 | 20 | Arch Linux: 21 | 22 | ``` 23 | $ sudo pacman -S make python-sphinx python-sphinx_rtd_theme 24 | ``` 25 | 26 | Debian: 27 | 28 | ``` 29 | $ sudo apt-get install make python3-sphinx python3-sphinx-rtd-theme 30 | ``` 31 | 32 | Fedora: 33 | 34 | ``` 35 | $ sudo dnf install make python3-sphinx python3-sphinx_rtd_theme 36 | ``` 37 | 38 | macOS: 39 | 40 | ``` 41 | $ brew install python3 42 | $ pip3 install -U sphinx sphinx-rtd-theme 43 | $ export PYTHON_VERSION="3.9" 44 | $ export PATH="$PATH:${HOME}/Library/Python/${PTYHON_VERSION}/bin/" 45 | ``` 46 | 47 | openSUSE: 48 | 49 | ``` 50 | $ sudo zypper install python3-Sphinx python3-sphinx_rtd_theme 51 | ``` 52 | 53 | Some operating systems will install the `sphinx-build` binary with a different suffix to indicate that it is using Python 3. For ease of use, consider symlinking that to be `sphinx-build`. 54 | 55 | ``` 56 | $ sudo ln -s /usr/bin/sphinx-build-3* /usr/local/bin/sphinx-build 57 | ``` 58 | 59 | ## Usage 60 | 61 | Sphinx will save newly generated documents into the "build/" directory by default. 62 | 63 | ### Usage - Automatic 64 | 65 | ePub: 66 | ``` 67 | $ make epub 68 | ``` 69 | 70 | HTML: 71 | ``` 72 | $ make html 73 | ``` 74 | 75 | HTML via the Docker Engine (all operating systems): 76 | 77 | ``` 78 | $ docker run --rm -v ${PWD}:/docs sphinxdoc/sphinx /bin/sh -c 'pip install sphinx_rtd_theme && make html' 79 | ``` 80 | 81 | PDF: 82 | ``` 83 | $ make latexpdf 84 | ``` 85 | 86 | Text: 87 | ``` 88 | $ make text 89 | ``` 90 | 91 | ### Usage - Manual 92 | 93 | The "sphinx-build" command is more flexible by being able to add additional command-line arguments to it. It also does not require the "make" system package to be able to process and execute the Makefile. 94 | 95 | Specify the format that the reStructuredText should be transformed and output into, and both the source and build directories. 96 | 97 | ``` 98 | $ sphinx-build -b src/ build/ 99 | ``` 100 | 101 | ## Spell Checking 102 | 103 | A custom dictionary is provided to do spell checking. However, the `hunspell` command does not reliably use every word in the dictionary so manual review is still required. 104 | 105 | ``` 106 | $ hunspell -l -d en_US -p ./hunspell_dictionary_root_pages.txt src/*/*.rst 107 | ``` 108 | 109 | ## Translations 110 | 111 | Root Pages can also be translated into a different language. 112 | 113 | * Convert the documents' text into the gettext `*.pot` format. 114 | 115 | ``` 116 | $ make gettext 117 | ``` 118 | 119 | * Compile the `*.pot` files into the `*.po` format. 120 | 121 | ``` 122 | $ sphinx-intl update -p build/gettext -l 123 | ``` 124 | 125 | * Translate the `*.po` files. 126 | * Build the translated documentations. 127 | 128 | ``` 129 | $ make -e SPHINXOPTS="-D language=''" html 130 | ``` 131 | 132 | ## Contributing 133 | 134 | Root Pages is a rolling release. As new information is committed, it is shortly pushed into master after a quick review for technical writing standards and correct citation usage. 135 | 136 | All updates should be added to the reStructuredText files in the "src/" directory of this project. These documents are currently in English and translations are always welcome! 137 | 138 | A few quick notes about technical documentation: 139 | 140 | * Everything should be written in the third-person narrative. 141 | * Sentences should be easy-to-read and quick to the point. 142 | * Chicago style citation to sources are required for all pages except for linux_commands. 143 | * Linux Commands are assumed to reference the official manual and information pages provided by the software. 144 | * If assistance is required with the syntax of new citations, check out [Citation Machine](http://www.citationmachine.net/chicago). 145 | 146 | Recommended text editors: 147 | 148 | * Graphical User Interface (GUI): 149 | * [Atom](https://atom.io/) with these optional plugins: 150 | * [sphinx-preview](https://atom.io/packages/sphinx-preview). Hint: Open the rendered HTML preview page by pressing `CONTROL` + `ALT` + `o` together. 151 | * This requires the "brower-plus" plugin and that the current user have access to manage docker containers. 152 | * The ``docker`` container platform should be installed. The user running ``atom`` also needs privileges to manage docker containers. 153 | * [rst-snippets](https://atom.io/packages/rst-snippets). Hint: Create a generic Markdown or RST table outline and then press `CONTROL` + `ALT` + `t` together and then `ENTER` to automatically reformat it correctly. 154 | * Command-Line Interface (CLI): 155 | * [Vim](https://github.com/vim/vim) with this plugin: 156 | * [vim-rst-tables plugin](https://github.com/nvie/vim-rst-tables). 157 | 158 | RST header characters to use: 159 | 160 | 1. `=====` 161 | 2. `-----` 162 | 3. `~~~~~` 163 | 4. `^^^^^` 164 | 5. `'''''` 165 | 6. `&&&&&` 166 | 167 | Any arguments or options that are required for a command or configuration are marked in **bold**. 168 | 169 | ### New Contributors 170 | 171 | There are a lot of [issues open on GitHub that have the label "new content."](https://github.com/LukeShortCloud/rootpages/issues?q=is%3Aopen+is%3Aissue+label%3A%22new+content%22) These issues indicate that a new subject matter should be added into an existing document. These normally have at least one link to a source article that can be referenced or at least used as a starting point for further research. 172 | 173 | ### Quarterly Updates 174 | 175 | Every three months, Root Pages is tagged as a milestone release. The four releases in a year are: `YYYY.01.01`, `YYYY.04.01`, `YYYY.07.01`, and `YYYY.10.01`. Quarterly updates minimize breakage to bookmarks and links compared to a rolling release model. Formatting, grammar, and spelling errors should be checked and corrected before each tagged release. 176 | 177 | ### Yearly Updates 178 | 179 | The copyright year in `src/conf.py` needs to be updated. 180 | 181 | ## Legal 182 | 183 | ### License 184 | 185 | Root Pages, and all of it's content, is provided under the GNU Free Documentation License (GFDL) v1.3. Additional disclaimers related to warranty and liability from the GPLv3 license are also applied to this project. 186 | 187 | Files: 188 | 189 | * LICENSE 190 | * DISCLAIMER 191 | 192 | ### Plagiarism 193 | 194 | Root Pages strives to provide proper citation to the original authors to give credit where due. If there are any reports of plagiarism, please [open a new GitHub issue](https://github.com/LukeShortCloud/rootpages/issues) for it to get addressed. 195 | -------------------------------------------------------------------------------- /k8s/app/deploy-rootpages-main.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: Deployment 3 | apiVersion: apps/v1 4 | metadata: 5 | name: deploy-rootpages-main 6 | namespace: ns-rootpages 7 | labels: 8 | app: rootpages-main 9 | spec: 10 | replicas: 3 11 | selector: 12 | matchLabels: 13 | app: rootpages-main 14 | strategy: 15 | # This deals with a situation where a Kubernetes node reboots which leads to the "emptyDir" ephemeral storage being lost. 16 | type: Recreate 17 | template: 18 | metadata: 19 | labels: 20 | app: rootpages-main 21 | spec: 22 | initContainers: 23 | - name: sphinx 24 | image: sphinxdoc/sphinx:3.4.3 25 | command: 26 | - /bin/sh 27 | - -c 28 | - "pip install sphinx_rtd_theme && apt-get update && apt-get -y install git && rm -rf rootpages && git clone --branch main https://github.com/ekultails/rootpages.git && cd rootpages && make html && cd .. && mv ./rootpages/build/html/* ./ && rm -rf rootpages" 29 | env: 30 | - name: DEBIAN_FRONTEND 31 | value: noninteractive 32 | volumeMounts: 33 | - name: tmp-dir 34 | mountPath: /tmp 35 | workingDir: /tmp 36 | containers: 37 | - name: nginx 38 | image: nginx:1.19.0 39 | ports: 40 | - name: http 41 | containerPort: 80 42 | resources: 43 | limits: 44 | memory: 1Gi 45 | requests: 46 | memory: 256Mi 47 | volumeMounts: 48 | - name: tmp-dir 49 | mountPath: /usr/share/nginx/html 50 | readOnly: true 51 | readinessProbe: 52 | httpGet: 53 | path: / 54 | port: 80 55 | initialDelaySeconds: 5 56 | timeoutSeconds: 2 57 | volumes: 58 | - name: tmp-dir 59 | emptyDir: {} 60 | -------------------------------------------------------------------------------- /k8s/app/deploy-rootpages-stable.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: Deployment 3 | apiVersion: apps/v1 4 | metadata: 5 | name: deploy-rootpages-stable 6 | namespace: ns-rootpages 7 | labels: 8 | app: rootpages-stable 9 | spec: 10 | replicas: 3 11 | selector: 12 | matchLabels: 13 | app: rootpages-stable 14 | strategy: 15 | # This deals with a situation where a Kubernetes node reboots which leads to the "emptyDir" ephemeral storage being lost. 16 | type: Recreate 17 | template: 18 | metadata: 19 | labels: 20 | app: rootpages-stable 21 | spec: 22 | initContainers: 23 | - name: sphinx 24 | image: sphinxdoc/sphinx:3.4.3 25 | command: 26 | - /bin/sh 27 | - -c 28 | - "pip install sphinx_rtd_theme && apt-get update && apt-get -y install git && rm -rf rootpages && git clone --branch stable https://github.com/ekultails/rootpages.git && cd rootpages && make html && cd .. && mv ./rootpages/build/html/* ./ && rm -rf rootpages" 29 | env: 30 | - name: DEBIAN_FRONTEND 31 | value: noninteractive 32 | volumeMounts: 33 | - name: tmp-dir 34 | mountPath: /tmp 35 | workingDir: /tmp 36 | containers: 37 | - name: nginx 38 | image: nginx:1.19.0 39 | ports: 40 | - name: http 41 | containerPort: 80 42 | resources: 43 | limits: 44 | memory: 1Gi 45 | requests: 46 | memory: 256Mi 47 | volumeMounts: 48 | - name: tmp-dir 49 | mountPath: /usr/share/nginx/html 50 | readOnly: true 51 | readinessProbe: 52 | httpGet: 53 | path: / 54 | port: 80 55 | initialDelaySeconds: 5 56 | timeoutSeconds: 2 57 | volumes: 58 | - name: tmp-dir 59 | emptyDir: {} 60 | -------------------------------------------------------------------------------- /k8s/app/ing-rootpages.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: Ingress 3 | apiVersion: networking.k8s.io/v1 4 | metadata: 5 | name: ing-rootpages 6 | namespace: ns-rootpages 7 | labels: 8 | app: rootpages 9 | annotations: 10 | cert-manager.io/cluster-issuer: "clusterissuer-letsencrypt-production" 11 | acme.cert-manager.io/http01-edit-in-place: "true" 12 | cert-manager.io/issue-temporary-certificate: "true" 13 | nginx.org/rewrites: "serviceName=svc-rootpages-main rewrite=/;serviceName=svc-rootpages-stable rewrite=/" 14 | spec: 15 | ingressClassName: nginx 16 | tls: 17 | - hosts: 18 | - rootpages.lukeshort.cloud 19 | secretName: secret-tls-rootpages-lukeshort-cloud 20 | rules: 21 | - host: rootpages.lukeshort.cloud 22 | http: 23 | paths: 24 | - backend: 25 | service: 26 | name: svc-rootpages-stable 27 | port: 28 | number: 80 29 | path: / 30 | pathType: Prefix 31 | - backend: 32 | service: 33 | name: svc-rootpages-stable 34 | port: 35 | number: 80 36 | path: /stable 37 | pathType: Prefix 38 | - backend: 39 | service: 40 | name: svc-rootpages-main 41 | port: 42 | number: 80 43 | path: /latest 44 | pathType: Prefix 45 | -------------------------------------------------------------------------------- /k8s/app/svc-rootpages-main.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: Service 3 | apiVersion: v1 4 | metadata: 5 | name: svc-rootpages-main 6 | namespace: ns-rootpages 7 | labels: 8 | app: rootpages-main 9 | spec: 10 | ports: 11 | - name: http 12 | port: 80 13 | selector: 14 | app: rootpages-main 15 | type: ClusterIP 16 | -------------------------------------------------------------------------------- /k8s/app/svc-rootpages-stable.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: Service 3 | apiVersion: v1 4 | metadata: 5 | name: svc-rootpages-stable 6 | namespace: ns-rootpages 7 | labels: 8 | app: rootpages-stable 9 | spec: 10 | ports: 11 | - name: http 12 | port: 80 13 | selector: 14 | app: rootpages-stable 15 | type: ClusterIP 16 | -------------------------------------------------------------------------------- /k8s/auth/ns-rootpages.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: Namespace 3 | apiVersion: v1 4 | metadata: 5 | name: ns-rootpages 6 | labels: 7 | auth: rootpages 8 | -------------------------------------------------------------------------------- /k8s/auth/role-github-actions.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: Role 3 | apiVersion: rbac.authorization.k8s.io/v1 4 | metadata: 5 | name: role-github-actions 6 | namespace: ns-rootpages 7 | labels: 8 | auth: rootpages 9 | rules: 10 | - apiGroups: 11 | - "" 12 | - "apps" 13 | - "extensions" 14 | resources: 15 | - deployments 16 | - ingresses 17 | - pods 18 | - replicasets 19 | - services 20 | verbs: 21 | - "*" 22 | -------------------------------------------------------------------------------- /k8s/auth/rolebinding-github-actions.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: RoleBinding 3 | apiVersion: rbac.authorization.k8s.io/v1 4 | metadata: 5 | name: rolebinding-github-actions 6 | namespace: ns-rootpages 7 | labels: 8 | auth: rootpages 9 | subjects: 10 | - kind: ServiceAccount 11 | name: sa-github-actions 12 | namespace: ns-rootpages 13 | roleRef: 14 | kind: Role 15 | name: role-github-actions 16 | apiGroup: rbac.authorization.k8s.io 17 | -------------------------------------------------------------------------------- /k8s/auth/sa-github-actions.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | kind: ServiceAccount 3 | apiVersion: v1 4 | metadata: 5 | name: sa-github-actions 6 | namespace: ns-rootpages 7 | labels: 8 | auth: rootpages 9 | -------------------------------------------------------------------------------- /k8s/auth/secret-sa-github-actions.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | apiVersion: v1 3 | kind: Secret 4 | metadata: 5 | name: sa-github-actions 6 | namespace: ns-rootpages 7 | annotations: 8 | kubernetes.io/service-account.name: sa-github-actions 9 | type: kubernetes.io/service-account-token 10 | -------------------------------------------------------------------------------- /src/_static/.gitignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/LukeShortCloud/rootpages/ef9291bf9430abba09f9c886ea3b6b49eb50020c/src/_static/.gitignore -------------------------------------------------------------------------------- /src/_templates/.gitignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/LukeShortCloud/rootpages/ef9291bf9430abba09f9c886ea3b6b49eb50020c/src/_templates/.gitignore -------------------------------------------------------------------------------- /src/administration/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Administration 4 | 5 | init 6 | linux_kernel 7 | mail_servers 8 | operating_systems 9 | package_managers 10 | performance_tuning 11 | -------------------------------------------------------------------------------- /src/administration/init.rst: -------------------------------------------------------------------------------- 1 | init 2 | ===== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Introduction 7 | ------------ 8 | 9 | init is the first process started by the Linux kernel once booted. It has the process ID (PID) of 1. This init process is in charge of starting services on boot and shutting them down when turning the computer off. systemd is the preferred init system of modern Linux distributions that has succeeded SysVinit. [1][2] 10 | 11 | systemd 12 | ------- 13 | 14 | File Locations 15 | ~~~~~~~~~~~~~~ 16 | 17 | systemd unit files can be created and used in any of these locations [3]: 18 | 19 | - ``/usr/lib/systemd/system/`` = Global systemd unit files installed by the system package manager. 20 | - ``/run/systemd/system/`` = Unit files that were created automatically by a program. 21 | - ``/etc/systemd/system/`` = User-created unit files. These override all other locations if a unit file exists with the same name. 22 | - ``~/.config/systemd/user/`` = User-created unit files that are managed locally by a user. These services only run while the user is logged in. These are managed with the command ``systemctl --user`` instead of the typical ``systemctl`` command. 23 | 24 | When adding new unit files, it is required to run this command to update the systemd cache about available unit files [4]: 25 | 26 | .. code-block:: sh 27 | 28 | $ sudo systemctl daemon-reload 29 | 30 | Creating a Unit File 31 | ~~~~~~~~~~~~~~~~~~~~ 32 | 33 | All unit files are ini configuration files that use this layout: 34 | 35 | .. code-block:: ini 36 | 37 | [Unit] 38 | Description= 39 | 40 | [] 41 | = 42 | 43 | [Install] 44 | WantedBy= 45 | 46 | Configuration options for unit files: 47 | 48 | - Run a system unit during a normal boot. 49 | 50 | .. code-block:: ini 51 | 52 | [Install] 53 | WantedBy=multi-user.target 54 | 55 | - Run a user unit during login. 56 | 57 | .. code-block:: sh 58 | 59 | [Install] 60 | WantedBy=default.target 61 | 62 | - Log standard output and/or standard error of a service to a file. 63 | 64 | .. code-block:: ini 65 | 66 | [Service] 67 | StandardOutput= 68 | StandardError= 69 | 70 | - Create a service that runs exactly once. 71 | 72 | .. code-block:: ini 73 | 74 | [Service] 75 | Type=oneshot 76 | ExecStart= 77 | ExecStart=/bin/systemctl --no-reload disable %n 78 | 79 | - Run the unit file if the file or directory does not exist. 80 | 81 | .. code-block:: ini 82 | 83 | [Unit] 84 | ConditionPathExists=! 85 | 86 | - Do not timeout while starting a service. 87 | 88 | .. code-block:: ini 89 | 90 | [Service] 91 | TimeoutSec=infinity 92 | 93 | - Start a service after a specified amount of time. 94 | 95 | .. code-block:: ini 96 | 97 | [Service] 98 | ExecStartPre=/bin/sleep 0.5 99 | ExecStart=/usr/bin/foobar 100 | 101 | - Automatically restart a service if it fails. [5] 102 | 103 | .. code-block:: ini 104 | 105 | [Service] 106 | ExecStart=/usr/bin/foobar 107 | Restart=on-failure 108 | RestartSec=0.1s 109 | 110 | - Run two or more commands. systemd will run one command at a time starting from top to bottom. 111 | 112 | .. code-block:: ini 113 | 114 | [Service] 115 | Type=oneshot 116 | ExecStart=/bin/sh -c "echo foo" 117 | ExecStart=/bin/sh -c "echo bar" 118 | RemainAfterExit=yes 119 | TimeoutSec=0 120 | 121 | - Start a unit after the networking service is online. If there is no network interface on the computer, then systemd will consider the networking services to be online. 122 | 123 | .. code-block:: ini 124 | 125 | [Unit] 126 | After=network-online.target 127 | Wants=network-online.target 128 | 129 | - Depending on the networking service used, enable it to wait to be online. [6] 130 | 131 | .. code-block:: sh 132 | 133 | $ sudo systemctl enable NetworkManager-wait-online.service 134 | 135 | .. code-block:: sh 136 | 137 | $ sudo systemctl enable systemd-networkd-wait-online.service 138 | 139 | - Configure environment variables in the systemd unit file or source them from an external file. [8] 140 | 141 | .. code-block:: ini 142 | 143 | [Service] 144 | Environment=foo=bar 145 | EnvironmentFile=/app/env 146 | 147 | .. code-block:: sh 148 | 149 | $ cat /app/env 150 | app_host=127.0.0.1 151 | app_address=80 152 | 153 | Preset Files 154 | ~~~~~~~~~~~~ 155 | 156 | System packages can define if a unit should be enabled or disabled by default. [7] 157 | 158 | - Create a file called ``/usr/lib/systemd/system-preset/.``. 159 | - Edit the file with the contents of ``enable .`` or ``disable ``. 160 | 161 | Enable Services on Boot 162 | ~~~~~~~~~~~~~~~~~~~~~~~ 163 | 164 | Enable a system service to start on boot. [9] 165 | 166 | - Automatically: 167 | 168 | .. code-block:: sh 169 | 170 | $ sudo systemctl enable 171 | 172 | - Manually: 173 | 174 | .. code-block:: sh 175 | 176 | $ sudo ln -s /usr/lib/systemd/system/.service /etc/systemd/system/multi-user.target.wants/.service 177 | 178 | Enable a user service to start when the login. [10] 179 | 180 | - Automatically: 181 | 182 | .. code-block:: sh 183 | 184 | $ systemctl --user enable 185 | 186 | - Manually: 187 | 188 | .. code-block:: sh 189 | 190 | $ ln -s ~/.config/systemd/user/.service ~/.config/systemd/user/default.target.wants/.service 191 | 192 | journald 193 | ~~~~~~~~ 194 | 195 | Introduction 196 | ^^^^^^^^^^^^ 197 | 198 | journald is a modern replacement to syslog for gathering and storing all system logs. [11] 199 | 200 | View all logs: 201 | 202 | .. code-block:: sh 203 | 204 | $ sudo journalctl --all 205 | 206 | View logs for a specific system service: 207 | 208 | .. code-block:: sh 209 | 210 | $ sudo journalctl --unit 211 | 212 | View logs for a specific user service [12]: 213 | 214 | .. code-block:: sh 215 | 216 | $ journalctl --user --user-unit 217 | 218 | Configuration 219 | ^^^^^^^^^^^^^ 220 | 221 | Use empheral logs in RAM to minimize writes (these will be lost on shutdown) [13]: 222 | 223 | .. code-block:: sh 224 | 225 | $ sudo -E ${EDITOR} /etc/systemd/journald.conf 226 | [Journal] 227 | Storage=volatile 228 | 229 | History 230 | ------- 231 | 232 | - `Latest `__ 233 | 234 | Bibliography 235 | ------------ 236 | 237 | 1. "What is an init system?" Fedora Magazine. October 31, 2015. Accessed May 11, 2023. https://fedoramagazine.org/what-is-an-init-system/ 238 | 2. "init." ArchWiki. March 12, 2023. Accessed May 11, 2023. https://wiki.archlinux.org/title/init 239 | 3. "Understanding Systemd Units and Unit Files." DigitalOcean Tutorials. February 17, 2015. Accessed May 11, 2023. https://www.digitalocean.com/community/tutorials/understanding-systemd-units-and-unit-files 240 | 4. "Where do I put my systemd unit file?" Unix & Linux Stack Exchange. March 10, 2023. Accessed May 11, 2023. https://unix.stackexchange.com/questions/224992/where-do-i-put-my-systemd-unit-file 241 | 5. "Auto-restart a crashed service in systemd." Mattias Geniar. January 13, 2020. Accessed May 11, 2023. https://ma.ttias.be/auto-restart-crashed-service-systemd/ 242 | 6. "Network Configuration Synchronization Points." systemd.io. 2022. Accessed May 11, 2023. https://systemd.io/NETWORK_ONLINE/ 243 | 7. "systemd.preset." systemd. Accessed May 16, 2023. https://www.freedesktop.org/software/systemd/man/systemd.preset.html 244 | 8. "Using environment variables in systemd units." Flatcar Container Linux. Accessed August 29, 2023. https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/ 245 | 9. "Use systemd to Start a Linux Service at Boot." Linode Docs. March 9, 2023. Accessed September 8, 2023. https://www.linode.com/docs/guides/start-service-at-boot/ 246 | 10. "Start a systemd user service at boot." Super User. August 14, 2023. Accessed September 8, 2023. https://superuser.com/questions/1025091/start-a-systemd-user-service-at-boot 247 | 11. "Why Journald?" SolarWinds Loggly. January 6, 2016. Accessed June 20, 2025. https://www.loggly.com/blog/why-journald/ 248 | 12. "[systemd-devel] How to allow a user to use journalctl to see user-specific systemd service logs?" Narkive Mailing List Archive. October 15, 2016. Accessed June 20, 2025. https://systemd-devel.freedesktop.narkive.com/iwp5tMZD/how-to-allow-a-user-to-use-journalctl-to-see-user-specific-systemd-service-logs 249 | 13. "journald.conf." systemd.index. Accessed June 20, 2025. https://www.freedesktop.org/software/systemd/man/latest/journald.conf.html 250 | -------------------------------------------------------------------------------- /src/administration/mail_servers.rst: -------------------------------------------------------------------------------- 1 | Mail Servers 2 | ============ 3 | 4 | .. contents:: Table of Contents 5 | 6 | Mail transfer agents (MTAs) are servers that are used to receive local 7 | e-mail and send outgoing e-mail. 8 | 9 | Postfix 10 | ------- 11 | 12 | Configuration options: 13 | 14 | - myhostname = The hostname of the mail server. 15 | 16 | - Default: If a fully qualified domain name (FQDN) is configured on the Unix machine then Postfix will use that. 17 | 18 | - mynetworks = Define the networks that are allowed to send e-mails. 19 | 20 | - Default: 127.0.0.0/8 21 | 22 | - mydestination = Define allowed destinations for e-mails. 23 | 24 | - Default: ``$myhostname localhost.$mydomain localhost`` 25 | 26 | - relayhost = Define the server to forward mail to. [1] 27 | 28 | Null Client Configuration 29 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 30 | 31 | In a null client configuration, mail is not accepted by the mail server. 32 | It only forwards local e-mails to another MTA. 33 | 34 | Example - Forward all e-mails from the localhost to the server at the 35 | 10.0.0.1 address. 36 | 37 | .. code-block:: sh 38 | 39 | myhostname = server.rootpages.tld 40 | mydomain = rootpages.tld 41 | myorigin = $mydomain 42 | inet_interfaces = loopback-only 43 | mydestination = 44 | relayhost = 10.0.0.1 45 | 46 | Gateway Configuration 47 | ~~~~~~~~~~~~~~~~~~~~~ 48 | 49 | In a gateway-client setup, mail is forwarded from the one or more 50 | specified networks to another MTA. 51 | 52 | Example - Forward all e-mails from localhost and from the 10.0.0.0/24 53 | network to the 10.0.0.1 server. 54 | 55 | .. code-block:: ini 56 | 57 | myhostname = server.example.com 58 | mydomain = example.com 59 | myorigin = $mydomain 60 | inet_interfaces = all 61 | mydestination = $myhostname localhost.$mydomain localhost $mydomain 62 | mynetworks = 10.0.0.0/24 127.0.0.0/8 63 | relayhost = 10.0.0.1 64 | 65 | [2][3] 66 | 67 | History 68 | ------- 69 | 70 | - `Latest `__ 71 | - `< 2019.01.01 `__ 72 | - `< 2018.01.01 `__ 73 | 74 | Bibliography 75 | ------------ 76 | 77 | 1. "Postfix Basic Configuration." Postfix. Accessed October 1, 2016. 78 | http://www.postfix.org/BASIC\_CONFIGURATION\_README.html 79 | 2. "Postfix Standard Configuration." Postfix. Accessed October 1, 2016. 80 | http://www.postfix.org/STANDARD\_CONFIGURATION\_README.html 81 | 3. "Configure a system to forward all email to a central mail server." 82 | CertDepot. November 25, 2015. Accessed October 1, 2016. 83 | https://www.certdepot.net/rhel7-configure-system-forward-email-central-mail-server/ 84 | -------------------------------------------------------------------------------- /src/administration/performance_tuning.rst: -------------------------------------------------------------------------------- 1 | Performance Tuning 2 | =================== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Linux Kernel Version 7 | -------------------- 8 | 9 | - Use the latest stable `upstream Linux kernel `__ for the best performance. 10 | 11 | - Despite claims of custom kernels providing enhanced performance, benchmarks show that in most cases they are still not as fast as the upstream Linux kernel. [1] The LTS Linux kernel is slower and does not support newer hardware compared to the latest stable version but it is more stable. [2] 12 | 13 | - Use at least Linux kernel 6.6 [3] to get the low latency benefits of the new EEVDF CPU scheduler. [4] 14 | 15 | Minimize Writes 16 | --------------- 17 | 18 | Introduction 19 | ~~~~~~~~~~~~ 20 | 21 | By moving more writes into RAM, both (1) the lifespan of a storage device and (2) the speed of a computer will be faster. 22 | 23 | Swap 24 | ~~~~ 25 | 26 | - Do not use a swap file. Instead, configure zram with lz4 compression and other optimized setings. Refer to `zram <../storage/file_systems.html#zram>`__. 27 | 28 | .. code-block:: sh 29 | 30 | $ sudo -E ${EDITOR} /etc/sysctl.d/99-zram.conf 31 | vm.swappiness = 180 32 | vm.watermark_boost_factor = 0 33 | vm.watermark_scale_factor = 125 34 | vm.page-cluster = 1 35 | $ sudo -E ${EDITOR} /etc/systemd/zram-generator.conf 36 | [zram0] 37 | compression-algorithm = lz4 38 | zram-size = ram * 2 39 | $ sudo systemctl enable systemd-zram-setup@zram0.service 40 | 41 | Ephemeral Logs 42 | ~~~~~~~~~~~~~~ 43 | 44 | Thes changes generally reduce the amount of logs for security and troubleshooting purposes. In exchange, a storage device will have a longer lifespan. 45 | 46 | 47 | - Use ``tmpfs`` as the file system for ``/tmp``, ``/var/log``, and ``/var/tmp`` mounts in ``/etc/fstab``. Refer to `ramfs and tmpfs <../storage/file_systems.html#ramfs-and-tmpfs>`__. 48 | 49 | - Store journald logs in memory. Refer to `journald configuration `__. 50 | 51 | .. code-block:: sh 52 | 53 | $ sudo -E ${EDITOR} /etc/systemd/journald.conf 54 | [Journal] 55 | Storage=volatile 56 | 57 | - Use the mount options ``noatime,nodiratime`` in ``/etc/fstab``. Refer to `Mount Options <../storage/file_systems.html#mount-options>`__. 58 | 59 | Delay Writes 60 | ~~~~~~~~~~~~ 61 | 62 | Delay storage writes to reduce the wear on the storage device's lifespan. These changes can lead to data loss if there is a power outage. 63 | 64 | - Keep writes in RAM for much longer. Refer to `Memory Caching `__. 65 | 66 | .. code-block:: sh 67 | 68 | $ sudo -E ${EDITOR} /etc/sysctl.d/50-ram-write-cache.conf 69 | vm.dirty_background_ratio = 40 70 | vm.dirty_ratio = 80 71 | vm.vfs_cache_pressure = 50 72 | 73 | - Increase the commit time (the interval before syncing writes to the storage device) to 5 minutes by using the mount option ``commit=300`` in ``/etc/fstab``. There may be noticeable lag or a system hang if the interval is too long or if the drive is too slow. Refer to `Mount Options <../storage/file_systems.html#mount-options>`__. 74 | 75 | History 76 | ------- 77 | 78 | - `Latest `__ 79 | 80 | Bibliography 81 | ------------ 82 | 83 | 1. "The Performance Impact From Different Arch Linux Kernel Flavors." Phoronix. January 25, 2023. Accessed December 29, 2023. https://www.phoronix.com/review/arch-linux-kernels-2023 84 | 2. "Why and How to install the LTS kernel in Arch Linux." Average Linux User. August 23, 2018. Accessed December 29, 2023. https://averagelinuxuser.com/the-lts-kernel-in-arch-linux/ 85 | 3. "EEVDF Scheduler Merged For Linux 6.6, Intel Hybrid Cluster Scheduling Re-Introduced." Phoronix. August 29, 2023. Accessed February 17, 2024. https://www.phoronix.com/news/Linux-6.6-EEVDF-Merged 86 | 4. "An EEVDF CPU scheduler for Linux." LWN.net. March 9, 2023. Accessed February 17, 2024. https://lwn.net/Articles/925371/ 87 | -------------------------------------------------------------------------------- /src/automation/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Automation 4 | 5 | ansible 6 | puppet 7 | -------------------------------------------------------------------------------- /src/commands/clustering.rst: -------------------------------------------------------------------------------- 1 | Clustering 2 | ========== 3 | 4 | .. contents:: Table of Contents 5 | 6 | See also: Administrative, Firewalls, Networking 7 | 8 | IPVS 9 | ---- 10 | 11 | Linux Virtual Server provides a way to load balance TCP and UDP connections. 12 | 13 | ipvsadm 14 | ~~~~~~~ 15 | 16 | .. csv-table:: 17 | :header: Usage, Explanation, Example 18 | :widths: 20, 20, 20 19 | 20 | "-A", "add a load balancer", "" 21 | "-a", "add a node to distribute connections", "" 22 | "-t ", "TCP service", "" 23 | "-u ", "UDP service", "" 24 | "-s {rr|lc|dh}", "set the scheduling method (i.e. round robin, least connections or destination IP/hash)", "" 25 | "-l", "list the current configuration", "" 26 | "-S, --save", "print the configuration to stdout", "" 27 | "-R, --restore", "restore the configuration from a file", "" 28 | "-C", "clear the current configuration", "" 29 | 30 | History 31 | ------- 32 | 33 | - `Latest `__ 34 | - `< 2019.01.01 `__ 35 | -------------------------------------------------------------------------------- /src/commands/compression.rst: -------------------------------------------------------------------------------- 1 | Compression 2 | =========== 3 | 4 | .. contents:: Table of Contents 5 | 6 | bzip 7 | ---- 8 | 9 | bzip2 10 | ~~~~~ 11 | 12 | Package: bzip2 13 | 14 | Files with the ".bz2" extension are compressed. 15 | 16 | .. csv-table:: 17 | :header: Usage, Explanation 18 | :widths: 20, 20 19 | 20 | "-v", "verbosely display output" 21 | 22 | cpio 23 | ---- 24 | 25 | cpio 26 | ~~~~ 27 | 28 | Package: cpio 29 | 30 | ``cpio`` means copy input/output. This format is used for RPMs. 31 | 32 | .. csv-table:: 33 | :header: Usage, Explanation 34 | :widths: 20, 20 35 | 36 | "-id", "extract files AND directories" 37 | 38 | .. csv-table:: 39 | :header: Example, Explanation 40 | :widths: 20, 20 41 | 42 | "rpm2cpio httpd.rpm | cpio -id", "extract files and directories from the Apache RPM" 43 | 44 | dtrx 45 | ---- 46 | 47 | dtrx 48 | ~~~~ 49 | 50 | Do the right extract (dtrx) is a universal compression utility for all formats. By default it runs in an interactive mode. 51 | 52 | .. csv-table:: 53 | :header: Usage, Explanation 54 | :widths: 20, 20 55 | 56 | "-m", "extract metadata from '.rpms', '.deb', or '.gem' packages" 57 | 58 | gzip 59 | ---- 60 | 61 | gzip 62 | ~~~~ 63 | 64 | Package: gzip 65 | 66 | Files with the ".gz" extension use gzip compression 67 | 68 | .. csv-table:: 69 | :header: Usage, Explanation 70 | :widths: 20, 20 71 | 72 | "-d", "decompress a file" 73 | "-r", "recursively compress files" 74 | "-v", "verbosely display output" 75 | 76 | pigz 77 | ~~~~ 78 | 79 | ``pigz`` provides automatic multi-threaded compression and decompression for ``gzip``. See ``gzip`` for possible arguments. 80 | 81 | rar 82 | --- 83 | 84 | rar 85 | ~~~ 86 | 87 | .. csv-table:: 88 | :header: Usage, Explanation 89 | :widths: 20, 20 90 | 91 | "-v", "verbosely display output" 92 | 93 | unrar 94 | ~~~~~ 95 | 96 | star 97 | ---- 98 | 99 | This archive tool provides the ability to retain special ACL permissions. 100 | 101 | star 102 | ~~~~ 103 | 104 | Package: star 105 | 106 | ``star`` provides extra capabilities to ``tar`` that allow for properly storing various types of attributes. 107 | 108 | .. csv-table:: 109 | :header: Usage, Explanation 110 | :widths: 20, 20 111 | 112 | "-x", "extract" 113 | "-v", "verbosely" 114 | "-f=", "provide the full file path to the '.star' archive" 115 | "-xattr", "preserve extended attributes such as SELinux permissions" 116 | 117 | tar 118 | --- 119 | 120 | tar 121 | ~~~ 122 | 123 | Package: tar 124 | 125 | Files with the ".tar" extension are archived (not compressed). 126 | 127 | .. csv-table:: 128 | :header: Usage, Explanation 129 | :widths: 20, 20 130 | 131 | "-x", "extracts a tar file" 132 | "-k", "do not delete existing files" 133 | "-c", "create a tar file" 134 | "-f", "use archive file" 135 | "-t", "lists files inside a tar file" 136 | "-T", "specify a file of directory/file names to tar" 137 | "-v", "verbosely display output" 138 | "-z", "compresses the archive using gzip to make a .tar.gz file" 139 | "-J", "uses xz compression" 140 | "-C", "specify the directory to extract to" 141 | "--selinux", "keep SELinux permissions" 142 | "--acls", "keep ACLs" 143 | "--xattrs", "keep extended attributes" 144 | 145 | .. csv-table:: 146 | :header: Example, Explanation 147 | :widths: 20, 20 148 | 149 | "-zcvf /home /root/home_backup.tar.gz", "create a backup of the home directory" 150 | 151 | xz 152 | -- 153 | 154 | xz 155 | ~~ 156 | 157 | Package: xz 158 | 159 | Best for compressing text files (saves the most space). 160 | 161 | .. csv-table:: 162 | :header: Usage, Explanation 163 | :widths: 20, 20 164 | 165 | "-z, --compress", "compress files" 166 | "-d, --decompress", "decompress files" 167 | "--threads 0", "use the number of hyperthreads available from the CPU for faster processing" 168 | "-0", "fast compression, takes less time" 169 | "-9", "high compression, takes longer" 170 | 171 | zip 172 | --- 173 | 174 | unzip 175 | ~~~~~ 176 | 177 | .. csv-table:: 178 | :header: Usage, Explanation 179 | :widths: 20, 20 180 | 181 | -d , specify a destination directory to extract to 182 | -j, decompress files to the current working directory 183 | -l, list contents of the archive 184 | 185 | .. csv-table:: 186 | :header: Example, Explanation 187 | :widths: 20, 20 188 | 189 | -j , decompress a specific file and save it to the current working directory 190 | 191 | jar 192 | ~~~ 193 | 194 | Package: java-openjdk 195 | 196 | Jar files are Java applications that are compressed using ``zip``. 197 | 198 | .. csv-table:: 199 | :header: Usage, Explanation 200 | :widths: 20, 20 201 | 202 | "cf", "create a Jar archive" 203 | "xf", "extract a Jar archive" 204 | 205 | zip 206 | ~~~ 207 | 208 | Package: zip 209 | 210 | .. csv-table:: 211 | :header: Usage, Explanation 212 | :widths: 20, 20 213 | 214 | "-v", "verbosely display output" 215 | "-r", "recursively; for directories" 216 | 217 | .. csv-table:: 218 | :header: Example, Explanation 219 | :widths: 20, 20 220 | 221 | "-r root_archive.zip /root/", "create a zip archive of the root user home directory" 222 | 223 | History 224 | ------- 225 | 226 | - `Latest `__ 227 | - `< 2019.01.01 `__ 228 | -------------------------------------------------------------------------------- /src/commands/configuration_management.rst: -------------------------------------------------------------------------------- 1 | Configuration Management 2 | ======================== 3 | 4 | .. contents:: Table of Contents 5 | 6 | See also: Administrative, LFH, Shell 7 | 8 | Ansible 9 | ------- 10 | 11 | ansible 12 | ~~~~~~~~ 13 | 14 | Package: ansible 15 | 16 | .. csv-table:: 17 | :header: Usage, Explanation 18 | :widths: 20, 20 19 | 20 | "all", "connect to all nodes" 21 | "-m -a '='", "run an Ansible module and then provide it arguments" 22 | "-m ping", "run the ping module to see if Ansible can connect to the inventory" 23 | "-m shell -a ''", "use the shell module to execute shell commands remotely with use all of the given arguments" 24 | "-m setup", "show all facts for one host" 25 | "--ssh-extra-args=''", "specify additional SSH options" 26 | "-u ", "connect as a specific user" 27 | "--sudo", "run Ansible tasks via sudo as that user" 28 | "-e", "specify extras variables in YAML or JSON format" 29 | "-f", "the number of forked processes to use to run tasks on multiple hosts; the default is to run on 5 hosts at a time; this is similar to the 'serial' module" 30 | " --list-hosts", "list all hosts in a given inventory group" 31 | 32 | ansible-config 33 | ~~~~~~~~~~~~~~ 34 | 35 | Package: ansible >= 2.4 36 | 37 | .. csv-table:: 38 | :header: Usage, Explanation 39 | :widths: 20, 20 40 | 41 | "view", "view the full configuration file" 42 | "dump", "view all of the configuration settings that are loaded" 43 | "list", "view all the available configuration settings and their descriptions" 44 | 45 | ansible-doc 46 | ~~~~~~~~~~~ 47 | 48 | Package: ansible 49 | 50 | .. csv-table:: 51 | :header: Usage, Explanation 52 | :widths: 20, 20 53 | 54 | "-l", "list all of the available modules" 55 | "", "show documentation about a specified " 56 | "--snippet ", "provide a YAML template for available options in the module and a brief explanation of each possible option" 57 | -t lookup -l, show all Ansible lookups 58 | -t lookup , show documentation about a specific lookup 59 | 60 | ansible-playbook 61 | ~~~~~~~~~~~~~~~~ 62 | 63 | .. csv-table:: 64 | :header: Usage, Explanation 65 | :widths: 20, 20 66 | 67 | "-i ", "specify an inventory (host/group) file" 68 | "-vvv", "verbose debug logging" 69 | "--list-tags", "list the tags in the Playbook" 70 | "--list-hosts", "list all of the hosts that the Playbook will run on" 71 | "--tags", "run only tasks with a certain tag keyword" 72 | "--skip-tags", "skip tasks that contain a certain tag" 73 | "--step", "run a Playbook task-by-task, asking the user if they want to continue" 74 | "--start-at-task", "start at a specific subtask" 75 | "--limit ", "limit the Playbook to only run on specific hosts" 76 | "--limit @", "limit the Playbook to only run on specific hosts listed in a file" 77 | "-e, --extra-vars", "define new or overriding variables" 78 | "-e @", "use variables from a specified file" 79 | "--diff", "show file and template changes if they replace an existing file" 80 | "--check", "run a test of the Playbook without making any changes to the remote system" 81 | "--syntax-check", "verify the syntax of the Playbook" 82 | 83 | .. csv-table:: 84 | :header: Example, Explanation 85 | :widths: 20, 20 86 | 87 | "-e '{""enable_nginx"": true}'", "pass a boolean variable, this can only be done using JSON" 88 | 89 | ansible-tower-service 90 | ~~~~~~~~~~~~~~~~~~~~~ 91 | 92 | Package: ansible-tower 93 | 94 | Manage all of the Ansible Tower services on a single node. 95 | 96 | .. csv-table:: 97 | :header: Usage, Explanation 98 | :widths: 20, 20 99 | 100 | "status", "show the status for all of the Ansible Tower services" 101 | "start", "" 102 | "stop", "" 103 | "restart", "" 104 | 105 | ansible-vault 106 | ~~~~~~~~~~~~~ 107 | 108 | Package: ansible 109 | 110 | Use Ansible to manage file encryption for playbooks. 111 | 112 | .. csv-table:: 113 | :header: Usage, Explanation 114 | :widths: 20, 20 115 | 116 | "create", "create a new encrypted file" 117 | encrypt_string, encrypt a string instead of a file 118 | "view", "open an encrypted file as read-only" 119 | "edit", "open an encrypted file to write" 120 | "--ask-vault-pass", "display a prompt to get the password from stdin" 121 | "--vault-password-file ", "specify the file containing the password" 122 | 123 | awx-manage 124 | ~~~~~~~~~~~ 125 | 126 | Package: ansible-tower 127 | 128 | The awx-manage command was formerly known as tower-manage. It is used to show and modify internal information about Ansible Tower. 129 | 130 | .. csv-table:: 131 | :header: Usage, Explanation 132 | :widths: 20, 20 133 | 134 | " --help", "show the help information for any of tower-manage argument" 135 | "changepassword ", "change the password for a user" 136 | "createsuperuser", "create a new administrator user" 137 | "inventory_import --source= --inventory-name=", "import a inventory file to an existing Tower inventory" 138 | "list_instances", "show all Ansible Tower hosts" 139 | "dbshell", "connect to the PostgreSQL server and open a interactive shell" 140 | 141 | molecule 142 | ~~~~~~~~ 143 | 144 | Package: python3-molecule 145 | 146 | A testing framework for Ansible that uses virtual test environments. 147 | 148 | .. csv-table:: 149 | :header: Usage, Explanation 150 | :widths: 20, 20 151 | 152 | init role -r, create a new role with support for Molecule 153 | test, "create the test environments, run tests, and then destroy the environment" 154 | test -s , run a full test on a specific scenario 155 | test --parallel, run tests in parallel 156 | test --destroy never, run tests but do not destroy the environment when done 157 | test --all, run a full test on all of the scenarios in the molecule/ directory 158 | test -d , run tests with a different driver 159 | create, create the environment 160 | destroy, delete the environment 161 | converge, create the environment and run all of the tests 162 | login, log into the environment 163 | 164 | setup.sh 165 | ~~~~~~~~ 166 | 167 | Package: ansible-tower-setup-latest.tar.gz 168 | 169 | The "setup.sh" script is part of the Ansible Tower setup tarball that is used for installation. 170 | 171 | .. csv-table:: 172 | :header: Usage, Explanation 173 | :widths: 20, 20 174 | 175 | "-b", "run the Playbook to backup Tower as a tarball in the current directory" 176 | "-r", "restore a backup of Tower" 177 | 178 | tower-cli 179 | ~~~~~~~~~ 180 | 181 | Package: python2-ansible-tower-cli 182 | 183 | A CLI for interfacing with the Ansible Tower API. 184 | 185 | .. csv-table:: 186 | :header: Usage, Explanation 187 | :widths: 20, 20 188 | 189 | "config {host|username|password}", "define the login credentials for accessing Tower" 190 | "config", "view the configuration file that is being used" 191 | "--help", "show the available commands" 192 | " --help", "show the help output for a specific argument" 193 | "--monitor", "show Job output" 194 | "job_template callback", "provision a Template to the local server" 195 | 196 | Puppet 197 | ------- 198 | 199 | All of the Puppet binaries, including Ruby related ones, are installed into ``/opt/puppetlabs/puppet/bin/``. 200 | 201 | facter 202 | ~~~~~~ 203 | 204 | Package: puppet-agent 205 | 206 | .. csv-table:: 207 | :header: Usage, Explanation 208 | :widths: 20, 20 209 | 210 | "", display the system facts 211 | "", display a specific fact and it's nested values 212 | -p, display the system and puppet facts 213 | -j, output to JSON 214 | -y, output to YAML 215 | parser validate, validate a manifest file 216 | 217 | .. csv-table:: 218 | :header: Example, Explanation 219 | :widths: 20, 20 220 | 221 | disks -y, show all of the facts about disks and output them into YAML 222 | 223 | puppet 224 | ~~~~~~ 225 | 226 | Package: puppet-agent 227 | 228 | .. csv-table:: 229 | :header: Usage, Explanation 230 | :widths: 20, 20 231 | 232 | apply --noop --show_diff .pp, run in a dry-run and show the differences of what would have been changed 233 | --version, show the Puppet version 234 | 235 | History 236 | ------- 237 | 238 | - `Latest `__ 239 | - `< 2019.01.01 `__ 240 | -------------------------------------------------------------------------------- /src/commands/firewalls.rst: -------------------------------------------------------------------------------- 1 | Firewalls 2 | ========= 3 | 4 | .. contents:: Table of Contents 5 | 6 | See also: Networking, Security 7 | 8 | iptables 9 | -------- 10 | 11 | iptables 12 | ~~~~~~~~ 13 | 14 | Package: iptables-services 15 | 16 | .. csv-table:: 17 | :header: Usage, Explanation, Example 18 | :widths: 20, 20, 20 19 | 20 | "-L", "list firewall rules", "" 21 | "-L ", "list firewall rules for a specific chain name", "" 22 | "-F", "remove all firewall rules", "" 23 | "-i", "specify an interface", "" 24 | "-A {INPUT|OUTPUT}", "append to this chain", "" 25 | "-t, --table {filter|nat|mangle|raw|security}", "edit a specific table", "" 26 | "-p {tcp|udp|any}", "the protocol to manipulate", "" 27 | "{--dport|--sport}", "destination or source port", "" 28 | "{-d|-s}", "destination or source IP", "" 29 | "-j {ACCEPT|DENY|REJECT|DROP}", "action for any matches" 30 | "!", "exclude options", "! -s 192.168.0.0/24" 31 | "-m state --state {NEW|ESTABLISHED|RELATED|INVALID}", "allow new, established, related, and/or invalid packets", "" 32 | 33 | iptables (example) 34 | ~~~~~~~~~~~~~~~~~~ 35 | 36 | .. csv-table:: 37 | :header: Usage, Explanation, Example 38 | :widths: 20, 20, 20 39 | 40 | "-A OUTPUT", "append the output rules...", "" 41 | "-p tcp", "...using the tcp protocol...", "" 42 | "--dport 80", "...to the destination port 80", "" 43 | "-j ACCEPT", "...and accept the connection.", "" 44 | 45 | Example of setting up a network address translation for all connections from eth1 and forward requests to/from eth0. 46 | 47 | .. code-block:: sh 48 | 49 | # Append to the POSTROUTING chain to allow masquerading (NAT) on the output interface eth0 50 | $ iptables -t nat -A POSTROUTING -o eth0 -j MAS 51 | # Append the FORWARD chain to allow requests from eth1 to eth0 52 | $ iptables -A FORWARD -i eth1 -o eth0 -j ACCEPT 53 | # Allow return requests back from eth1 to eth0 that are related to the outgoing packets 54 | $ iptables -A FORWARD -i eth0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT 55 | 56 | iptables --policy 57 | ~~~~~~~~~~~~~~~~~ 58 | 59 | Modify the default policy for the firewall. 60 | 61 | .. csv-table:: 62 | :header: Usage, Explanation, Example 63 | :widths: 20, 20, 20 64 | 65 | "{INPUT|OUTPUT|FORWARD}", "", "" 66 | "{ACCEPT|REJECT|DROP}", "", "" 67 | 68 | iptables-save 69 | ~~~~~~~~~~~~~ 70 | 71 | Save the iptables rules. 72 | 73 | .. csv-table:: 74 | :header: Usage, Explanation, Example 75 | :widths: 20, 20, 20 76 | 77 | "iptables-save > /etc/sysconfig/iptables", "save the iptables rules on RHEL/Fedora", "" 78 | 79 | Firewalld 80 | --------- 81 | 82 | The default firewall for RHEL >= 7. 83 | 84 | firewall-cmd 85 | ~~~~~~~~~~~~ 86 | 87 | .. csv-table:: 88 | :header: Usage, Explanation, Example 89 | :widths: 20, 20, 20 90 | 91 | "--get-default-zone", "shows the default loaded zone", "" 92 | "--get-active-zones", "shows loaded zone profiles", "" 93 | "--get-services", "show valid services", "" 94 | "--list-services", "show allowed services", "" 95 | "--list-rich-rules", "show the defined rich rules", "" 96 | "--add-service=", "allow a service", "" 97 | "--add-source=", "allow an IP or CIDR range through the firewall", "" 98 | "--zone=", "modify a specified firewalld zone", "" 99 | "--list-all", "show the open ports", "" 100 | "--add-port=/{tcp|udp} --permanent", "open a port, requires a reloading firewalld", "" 101 | "--add-masquerade", "enable IP and port forwarding", "" 102 | "--reload", "activate any permanent changes", "" 103 | 104 | firewall-cmd --add-rich-rule 105 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 106 | 107 | Add more complicated firewalld rules that are similar in syntax to iptables. 108 | 109 | .. csv-table:: 110 | :header: Usage, Explanation, Example 111 | :widths: 20, 20, 20 112 | 113 | "firewall-cmd --add-rich-rule=''", "add a new rule within single quotes", "" 114 | "rule family=""ipv[4|6]""", "start a new using IPv4 or IPv6...", "" 115 | "[source|destination][address|port]", "...using a source/destination address/port...", "" 116 | "[accept|reject|drop]", "...accept the connection, reject the connection with a message, or do not do anything with the packet.", "" 117 | "rule family=""ipv4"" source address="""" accept", "allow an IP address", "" 118 | 119 | firewall-config 120 | ~~~~~~~~~~~~~~~ 121 | 122 | A GUI for managing the firewalld configuration. 123 | 124 | Uncomplicated Firewall 125 | ---------------------- 126 | 127 | This is the default Ubuntu firewall. 128 | 129 | ufw 130 | ~~~ 131 | 132 | .. csv-table:: 133 | :header: Usage, Explanation, Example 134 | :widths: 20, 20, 20 135 | 136 | "status", "shows loaded rules", "" 137 | "enable", "start ufw", "" 138 | "disable", "stop ufw", "" 139 | "allow ", "allow all UDP and TCP connections to a port", "" 140 | "allow /", "allow only specific protocols on a port", "" 141 | "deny ", "deny all traffic to this port", "" 142 | "--dry-run", "do not make changes; only show what iptables rules will be made", "" 143 | 144 | History 145 | ------- 146 | 147 | - `Latest `__ 148 | - `< 2019.01.01 `__ 149 | -------------------------------------------------------------------------------- /src/commands/hardware.rst: -------------------------------------------------------------------------------- 1 | Hardware 2 | ======== 3 | 4 | .. contents:: Table of Contents 5 | 6 | See also: Administrative, Drives, Virtualization 7 | 8 | North Bridge 9 | ------------ 10 | 11 | dmidecode 12 | ~~~~~~~~~ 13 | 14 | View information about the motherboard and BIOS. 15 | 16 | lspci 17 | ~~~~~ 18 | 19 | .. csv-table:: 20 | :header: Usage, Explanation 21 | :widths: 20, 20 22 | 23 | "-m", "lists PCI hardware" 24 | 25 | lscpu 26 | ~~~~~ 27 | 28 | Display information about the current system's processors. 29 | 30 | lsusb 31 | ~~~~~ 32 | 33 | Display attached USB devices. 34 | 35 | sensors-detect 36 | ~~~~~~~~~~~~~~ 37 | 38 | Package: lm_sensors 39 | 40 | Automatically find sensors on your motherboard. This generates a configuration file to be used with the "sensors" command. 41 | 42 | sensors 43 | ~~~~~~~ 44 | 45 | Displays the current temperature of your devices. 46 | 47 | stress 48 | ~~~~~~ 49 | 50 | Package: stress 51 | 52 | A utility for stress testing the processor, RAM, and/or storage. 53 | 54 | .. csv-table:: 55 | :header: Usage, Explanation 56 | :widths: 20, 20 57 | 58 | "-c, --cpu", "spawn CPU workers" 59 | "-i, --io", "spawn I/O workers in RAM and storage devices" 60 | "-m,--vm", "spawns RAM workers" 61 | "--vm-bytes", "specify bytes to write to RAM" 62 | "-d, --hdd", "spawn I/O workers on the actual drive" 63 | "-t", "timeout time" 64 | "-v", "verbose" 65 | 66 | stress-ng 67 | ~~~~~~~~~ 68 | 69 | Package: stress-ng 70 | 71 | An updated "next generation" stress utility. 72 | 73 | netio 74 | ~~~~~ 75 | 76 | Stress test utility for networks. 77 | 78 | i8kctl 79 | ~~~~~~ 80 | 81 | Package: `i8kutils `__. 82 | 83 | A utility to manage fans on Dell laptops. By default, the BIOS will have full automatic control over the fans. That will need to be disabled for this utility to work properly. 84 | 85 | .. csv-table:: 86 | :header: Usage, Explanation 87 | :widths: 20, 20 88 | 89 | fan, show the current speed settings 90 | fan 0 0, disable both the left and right fan 91 | fan 1 1, set the fans to be on low speed 92 | fan 2 2, set the fans to be on max speed 93 | 94 | Audio 95 | ----- 96 | 97 | alsamixer 98 | ~~~~~~~~~ 99 | 100 | Package: alsa-utils 101 | 102 | A CLI utility for volume control of the speakers. 103 | 104 | speaker-test 105 | ~~~~~~~~~~~~ 106 | 107 | .. csv-table:: 108 | :header: Usage, Explanation 109 | :widths: 20, 20 110 | 111 | "-c 2", "test audio output on stereo speakers" 112 | "-D hw:", "test a specific audio device; you can get this information from /proc/asound/pcm" 113 | 114 | .. csv-table:: 115 | :header: Example, Explanation 116 | :widths: 20, 20 117 | 118 | "-D hw:0,0", "test the 0,0 speakers" 119 | 120 | Graphics 121 | -------- 122 | 123 | intel-gpu-tools 124 | ~~~~~~~~~~~~~~~ 125 | 126 | Monitor utility for Intel integrated graphics. 127 | 128 | nvidia-smi 129 | ~~~~~~~~~~ 130 | 131 | Monitor utility for Nvidia graphics cards. This only works with the proprietary "nvidia" driver. 132 | 133 | .. csv-table:: 134 | :header: Usage, Explanation 135 | :widths: 20, 20 136 | 137 | "", show the resource and power utilization of the card 138 | -i 0 -p1 , set the maximum amount of wattage that the first Nvidia card detected should use 139 | 140 | .. csv-table:: 141 | :header: Example, Explanation 142 | :widths: 20, 20 143 | 144 | -i 0 -p1 80, only allow the first Nvidia card to use up to 80 watts of power 145 | 146 | aticonfig 147 | ~~~~~~~~~ 148 | 149 | Monitor utility for AMD cards. This only works with the proprietary "fglrx" driver. 150 | 151 | .. csv-table:: 152 | :header: Usage, Explanation 153 | :widths: 20, 20 154 | 155 | "-odgc -odgt", "" 156 | 157 | radeontop 158 | ~~~~~~~~~ 159 | 160 | Monitor utility for AMD cards. This works with both the "fglrx" and open-source "radeon" driver. 161 | 162 | xrandr 163 | ~~~~~~ 164 | 165 | Configure different display settings. 166 | 167 | .. csv-table:: 168 | :header: Usage, Explanation 169 | :widths: 20, 20 170 | 171 | "--output --primary", "change the primary monitor" 172 | 173 | glxinfo 174 | ~~~~~~~ 175 | 176 | Displays information about the GPU driver and related libraries. 177 | 178 | .. csv-table:: 179 | :header: Example, Explanation 180 | :widths: 20, 20 181 | 182 | "glxinfo | grep ""OpenGL version""", "find the maximum supported OpenGL version" 183 | 184 | obmenu-generator 185 | ~~~~~~~~~~~~~~~~ 186 | 187 | Generate menu items for the Openbox window manager. 188 | 189 | .. csv-table:: 190 | :header: Usage, Explanation 191 | :widths: 20, 20 192 | 193 | -i, find and use icons for application 194 | -p, create a menu that will always search for the latest installed applications 195 | -s, create a menu once with the currently installed applications 196 | 197 | .. csv-table:: 198 | :header: Example, Explanation 199 | :widths: 20, 20 200 | 201 | -p -i, create a dynamic menu that contains icons for each application 202 | 203 | mhwd 204 | ~~~~ 205 | 206 | The Manjaro Hardware Detection utility is used to install hardware drivers on Manjaro Linux. 207 | 208 | .. csv-table:: 209 | :header: Usage, Explanation 210 | :widths: 20, 20 211 | 212 | -a pci {free|nonfree} 0300, install the graphics drivers automatically based on the hardware found 213 | -l -d {--pci}, view available drivers that can be installed (optionally only for PCI devices) 214 | -li -d {--pci|--usb|}, list installed drivers 215 | -i pci , manually install a new driver 216 | -f -i pci , force a re-install of a driver 217 | -r , remove a hardware driver 218 | 219 | IPMI 220 | ---- 221 | 222 | ipmitool 223 | ~~~~~~~~ 224 | 225 | Package: OpenIPMI-tools 226 | 227 | .. csv-table:: 228 | :header: Usage, Explanation 229 | :widths: 20, 20 230 | 231 | "-I lanplus -H -U -P {chassis|power} status", "remotely connect to IPMI to check the status of a particular component" 232 | "-A MD5", "use MD5 encryption for authentication" 233 | "user list 1", "show all users" 234 | "-I lanplus -H -U -P user set password 2 ", "reset password for a user" 235 | 236 | ipmitool lan 237 | ~~~~~~~~~~~~ 238 | 239 | Manage the network connection for the IPMI device. 240 | 241 | .. csv-table:: 242 | :header: Usage, Explanation 243 | :widths: 20, 20 244 | 245 | "print 1", "display the network settings" 246 | "set 1 ipsrc {static|dhcp}", "change the network mode" 247 | "set 1 ipaddr", "set the IP address" 248 | "set 1 netmask", "set the subnet mask" 249 | 250 | .. csv-table:: 251 | :header: Example, Explanation 252 | :widths: 20, 20 253 | 254 | "set 1 ipsrc static", "use static IP addressing" 255 | "set 1 ipaddr 192.168.1.101", "set the IP address" 256 | "set 1 netmask 255.255.255.0", "set the subnet mask" 257 | 258 | ipmicfg 259 | ^^^^^^^ 260 | 261 | Configure IPMI. 262 | 263 | .. csv-table:: 264 | :header: Usage, Explanation 265 | :widths: 20, 20 266 | 267 | "-raw 0x30 0x70 0x0c 0", "view the LAN mode (dedicated, shared, or failover)" 268 | "-raw 0x30 0x70 0x0c 1 0", "set the LAN mode to dedicated" 269 | "-raw 0x30 0x70 0x0c 1 1", "set the LAN mode to shared" 270 | "-raw 0x30 0x70 0x0c 1 2", "set the LAN mode to failover" 271 | 272 | lUpdate 273 | ^^^^^^^ 274 | 275 | IPMI firmware update utility. 276 | 277 | .. csv-table:: 278 | :header: Usage, Explanation 279 | :widths: 20, 20 280 | 281 | "-i kcs -f", "update IPMI's firmware" 282 | 283 | History 284 | ------- 285 | 286 | - `Latest `__ 287 | - `< 2019.01.01 `__ 288 | -------------------------------------------------------------------------------- /src/commands/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Commands 4 | 5 | clustering 6 | compression 7 | configuration_management 8 | firewalls 9 | hardware 10 | openstack 11 | package_managers 12 | permissions 13 | phones 14 | security 15 | software_code_management 16 | storage 17 | text_editors 18 | virtualization 19 | 20 | -------------------------------------------------------------------------------- /src/commands/phones.rst: -------------------------------------------------------------------------------- 1 | Phones 2 | ====== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Android 7 | ------- 8 | 9 | adb 10 | ~~~ 11 | 12 | .. csv-table:: 13 | :header: Usage, Explanation 14 | :widths: 20, 20 15 | 16 | devices, show connected devices that are fully booted 17 | reboot, reboot into the normal Android operating system 18 | reboot bootloader, reboot into the bootloader 19 | reboot recovery, reboot into the recovery mode 20 | reboot fastboot, reboot into the fastboot mode 21 | push, upload a file to the device 22 | pull, download a file from the device 23 | 24 | .. csv-table:: 25 | :header: Example, Explanation 26 | :widths: 20, 20 27 | 28 | push recovery.img /sdcard/, upload an image file to the internal sdcard storage of the phone 29 | 30 | fastboot 31 | ~~~~~~~~ 32 | 33 | .. csv-table:: 34 | :header: Usage, Explanation 35 | :widths: 20, 20 36 | 37 | devices, show connected Android devices in the boot or recovery mode 38 | boot .img, temporarily boot into a recovery image that is stored on the local computer 39 | flash recovery .img, install a new recovery utility (such as TWRP) 40 | flash .img, flash the image to a specific partition (it will only flash to A on A/B systems) 41 | flash --slot all .img, "flash the image to a specific A/B partition (bootloader, radio, or vendor) on Oreo and newer devices" 42 | 43 | History 44 | ------- 45 | 46 | - `Latest `__ 47 | - `< 2019.01.01 `__ 48 | -------------------------------------------------------------------------------- /src/commands/security.rst: -------------------------------------------------------------------------------- 1 | Security 2 | ======== 3 | 4 | .. contents:: Table of Contents 5 | 6 | See also: Firewalls, Permissions 7 | 8 | Anti-Virus 9 | ---------- 10 | 11 | clamscan 12 | ~~~~~~~~ 13 | 14 | A free and open source anti-virus command line utility. Run "freshclam" to update the anti-virus database. 15 | 16 | .. csv-table:: 17 | :header: Usage, Explanation 18 | :widths: 20, 20 19 | 20 | "-r", "recursively through folders" 21 | "-i", "only output infected files" 22 | "--move=", "specify path to move infected files to" 23 | 24 | Audit 25 | ----- 26 | 27 | Package: audit 28 | 29 | For Audit to work properly, the service needs to be started. 30 | 31 | .. code-block:: sh 32 | 33 | $ sudo systemctl start auditctl 34 | 35 | auditctl 36 | ~~~~~~~~ 37 | 38 | Log verbose modifications and access to a file. 39 | 40 | .. csv-table:: 41 | :header: Usage, Explanation 42 | :widths: 20, 20 43 | 44 | "-w", "watch a file" 45 | "-p arwx", "watch for appending, reading, writing and executing of the file" 46 | 47 | ausearch 48 | ~~~~~~~~ 49 | 50 | used after setting up auditctl on a file 51 | 52 | .. csv-table:: 53 | :header: Usage, Explanation 54 | :widths: 20, 20 55 | 56 | "-f", "views log of a given file" 57 | "-t", "check for changes during a certain time" 58 | 59 | 60 | Kerberos 61 | -------- 62 | 63 | kadmin (Command) 64 | ~~~~~~~~~~~~~~~~ 65 | 66 | Package: krb5-workstation 67 | 68 | Manage the Kerberos Distribution Center (KDC). 69 | 70 | .. csv-table:: 71 | :header: Usage, Explanation 72 | :widths: 20, 20 73 | 74 | "-q", "run interactive commands" 75 | 76 | kadmin (Interactive) 77 | ~~~~~~~~~~~~~~~~~~~~ 78 | 79 | .. csv-table:: 80 | :header: Usage, Explanation 81 | :widths: 20, 20 82 | 83 | "?", "view the available commands" 84 | "addprinc ", "create a new principal for a user" 85 | "addprinc host/", "create a new principal to allow authentication from a server" 86 | "addprinc nfs/", "create an NFS principal" 87 | "addprinc cifs/", "create a CIFS/SMB principal" 88 | "addprinc ftp/", "create a FTP principal" 89 | "ktadd host/", "save the principal to the /etc/krb5.keytab file" 90 | "ktremove host/", "remove the principal from the keytab file" 91 | "delprinc", "delete a principal" 92 | "listprincs", "list principals" 93 | 94 | klist 95 | ~~~~~ 96 | 97 | View authentication information about Kerberos. 98 | 99 | .. csv-table:: 100 | :header: Usage, Explanation 101 | :widths: 20, 20 102 | 103 | "", "show the current ticket validation status" 104 | "-k", "show the contents of the /etc/krb5.keytab file" 105 | 106 | kdestroy 107 | ~~~~~~~~ 108 | 109 | Revoke a user's Kerberos ticket. 110 | 111 | .. csv-table:: 112 | :header: Usage, Explanation 113 | :widths: 20, 20 114 | 115 | "", "write zeros to the cached ticket file to securely remove it" 116 | 117 | Local System 118 | ------------ 119 | 120 | Miscellaneous commands for managing security on local systems. 121 | 122 | genkey 123 | ~~~~~~ 124 | 125 | Package: crypto-keys 126 | 127 | Generate SSL/TLS certificates. 128 | 129 | .. csv-table:: 130 | :header: Usage, Explanation 131 | :widths: 20, 20 132 | 133 | "", "create a self-signed SSL" 134 | 135 | gpg 136 | ~~~ 137 | 138 | Package: gnupg 139 | 140 | .. csv-table:: 141 | :header: Usage, Explanation 142 | :widths: 20, 20 143 | 144 | "--output .gpg --encrypt ", "encrypt a specified file, saving it as a new file" 145 | "--output --decrypt .gpg", "decrypt an encrypted file, saving it as a new file" 146 | 147 | lastb 148 | ~~~~~ 149 | 150 | Package: util-linux 151 | 152 | .. csv-table:: 153 | :header: Usage, Explanation 154 | :widths: 20, 20 155 | 156 | "", "shows last failed login attempts" 157 | 158 | lastlog 159 | ~~~~~~~ 160 | 161 | Package: shadow-utils 162 | 163 | .. csv-table:: 164 | :header: Usage, Explanation 165 | :widths: 20, 20 166 | 167 | "", "shows inform about the last logins" 168 | 169 | sudo 170 | ~~~~ 171 | 172 | Package: sudo 173 | 174 | Allow non-root accounts to temporarily run privileged commands. 175 | 176 | .. csv-table:: 177 | :header: Usage, Explanation 178 | :widths: 20, 20 179 | 180 | "-E", "keeps sudo enabled for the current shell session" 181 | 182 | History 183 | ------- 184 | 185 | - `Latest `__ 186 | - `< 2019.01.01 `__ 187 | -------------------------------------------------------------------------------- /src/commands/template.rst: -------------------------------------------------------------------------------- 1 | Template 2 | ======== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Topic 7 | ----- 8 | 9 | command 10 | ~~~~~~~ 11 | 12 | Package: command-pkg 13 | 14 | .. csv-table:: 15 | :header: Usage, Explanation 16 | :widths: 20, 20 17 | 18 | arg1, This does foo. 19 | arg2, This does bar. 20 | 21 | .. csv-table:: 22 | :header: Example, Explanation 23 | :widths: 20, 20 24 | 25 | arg1 100, This will do foo 100 times. 26 | 27 | History 28 | ------- 29 | 30 | - `Latest `__ 31 | - `< 2019.01.01 `__ 32 | -------------------------------------------------------------------------------- /src/commands/text_editors.rst: -------------------------------------------------------------------------------- 1 | Text Editors 2 | ============ 3 | 4 | .. contents:: Table of Contents 5 | 6 | See also: Shell 7 | 8 | Vim 9 | --- 10 | 11 | vim (Command) 12 | ~~~~~~~~~~~~~ 13 | 14 | Vi IMproved (Vim) is an text with advanced features based on the original Vi. 15 | 16 | Package: vim 17 | 18 | .. csv-table:: 19 | :header: Usage, Explanation 20 | :widths: 20, 20 21 | 22 | "-M", "open a file in immutable (read-only) mode" 23 | "-x", "encrypt a file" 24 | "-d", "compare and edit two files in diff mode" 25 | 26 | vim (Interactive) 27 | ~~~~~~~~~~~~~~~~~ 28 | 29 | .. csv-table:: 30 | :header: Usage, Explanation, Example 31 | :widths: 20, 20, 20 32 | 33 | ":q!", "quit without saving changes" 34 | ":wq", "save and quit" 35 | ":x", "save and quit" 36 | "ZZ", "save and quit" 37 | ":set number", "show line numbers" 38 | ":set nu", "" 39 | ":set nonumber", "turn off line numbers" 40 | ":set nonu", "" 41 | ":", "go to the specified line number" 42 | ":split", "split vim into two horizontal screens" 43 | ":vsplit", "split vim into two vertical screens" 44 | ":vsplit ", "split vim into two vertical screens and open a different file in the new screen" 45 | "CTRL + w + ARROW_KEY", "move to that specified vim screen" 46 | ":recover", "reload the edited file from an old '.swp' file (from a VIM crash)" 47 | ":prev", "open up the last file that was opened by VIM" 48 | ":so %", "" 49 | ":source %", "install a Vim plugin" 50 | ":set nowrap", "disable text wrapping" 51 | ":set list", "show space and tab characters" 52 | ":set no list", "do not show space and tab characters" 53 | ":changes", "show changes in the current file" 54 | "y", "move cursor to the front of the line" 55 | "d", "cut line" 56 | "p", "paste after the cursor" 57 | "u", "undo" 58 | "CTRL+r", "redo (un-undo)" 59 | ".", "redo previous command again" 60 | "/", "search for a certain string" 61 | "n", "search for the next result" 62 | "N (Shift+n)", "show the previous search result" 63 | ":shell, :sh", "opens up a new shell session" 64 | ":ab", "this sets an abbreviation; when used it will transform into the setence you specify after the keyword" 65 | "di", "deletes until everything on the line until it reaches the delimiter" 66 | "dd", "delete the current line" 67 | ":%Tohtml", "turns the text file into a fully usable HTML file" 68 | "gg", "go to first line of the file" 69 | "G", "go to the last line of the file" 70 | "s/find/replace/g", "a sed-like find and replace for the current line only" 71 | "%s/find/replace/g", "a sed-like find and replace for the entire file" 72 | "CTRL+v", "visual line select mode; select columns and rows" 73 | "V (SHIFT + v)", "select multiple lines" 74 | "> (Shift + .)", "tab selected text" 75 | "^", "move cursor to the start of the line" 76 | "$", "move cursor to the end of the line" 77 | "gt", "switch between screens" 78 | "SHIFT+UP", "scroll the page up" 79 | "SHIFT+DOWN", "scroll the page down" 80 | "SHIFT+U", "set all selected characters to be upper case" 81 | "CTRL+O (CTRL + SHIFT + o)", "jump back to the previous place you were on" 82 | ":noh, :nohlsearch", "clear the last search result highlights" 83 | 84 | .. csv-table:: 85 | :header: Example, Explanation 86 | :widths: 20, 20 87 | 88 | ":ab hello Hello, how are you?", "set ""hello"" as an alias" 89 | "\di.", "delete all text on a line until it reaches a period" 90 | 91 | History 92 | ------- 93 | 94 | - `Latest `__ 95 | - `< 2019.01.01 `__ 96 | -------------------------------------------------------------------------------- /src/computer_hardware/accessories.rst: -------------------------------------------------------------------------------- 1 | Accessories 2 | =========== 3 | 4 | .. contents:: Table of Contents 5 | 6 | USB Ports 7 | --------- 8 | 9 | Universal Serial Bus (USB) is a common connector for accessories. Real world speeds for USB are about 30% less than the theoretical maximum speeds. 10 | 11 | .. csv-table:: 12 | :header: Name (New), Name (Original), Maximum Theoretical Speed (Gbps), Real World Speed (Gbps), Real World Speed (MBps) 13 | :widths: 20, 20, 20, 20, 20 14 | 15 | 16 | USB 4, "", 40, 32, 4000 17 | USB 3.2 Gen 2x2, USB 3.2, 20, 16, 2000 18 | USB 3.2 Gen 2x1, USB 3.1 and USB 3.1 Gen 2, 10, 7.2, 900 19 | USB 3.2 Gen 1x2, "", 10, 7.2, 900 20 | USB 3.2 Gen 1, USB 3.0 and USB 3.1 Gen 1, 5, 3.2, 400 21 | USB 2.0, "", 0.480, "", "" 22 | USB 1.1 Hi-Speed, "", 0.012, "", "" 23 | USB 1.1 Low Speed, "", 0.0015, "", "" 24 | 25 | [2] 26 | 27 | As of USB 4, Thunderbolt 4 is natively supported with all cables and interfaces. All Thunderbolt 3 interfaces are USB type-C but not all USB type-C interfaces are Thunderbolt. All Thunderbolt 4 interfaces are USB 4 and vice-versa. [3] 28 | 29 | USB Devices 30 | ----------- 31 | 32 | Polling Frequency 33 | ~~~~~~~~~~~~~~~~~ 34 | 35 | The polling frequency of a USB device can be set based on the type of device it is: 36 | 37 | - jspoll = Joystick (gamepad) 38 | - kbpoll = Keyboard 39 | - mousepoll = Mouse 40 | 41 | An interval of time in miliseconds is configurable for the polling frequency. The default interval is 10ms. Linux uses this equation to calculate the frequency (Hz) that it should use for checking input from a device: `` Hz = 1000 / ms``. A lower interval will make a device more responsive but it will also use more processing power. 42 | 43 | Here is how to change the pollling frequency: 44 | 45 | - Temporary 46 | 47 | - Syntax: 48 | 49 | .. code-block:: sh 50 | 51 | $ echo "" | sudo tee /sys/module/usbhid/parameters/ 52 | 53 | - Example (250 Hz USB mouse): 54 | 55 | .. code-block:: sh 56 | 57 | $ echo "4" | sudo tee /sys/module/usbhid/parameters/mousepoll 58 | 59 | - Permanent 60 | 61 | - Syntax: 62 | 63 | .. code-block:: sh 64 | 65 | $ sudo vim /etc/default/grub 66 | GRUB_CMDLINE_LINUX_DEFAULT="usbhid.=" 67 | $ sudo grub-mkconfig -o /boot/grub/grub.cfg 68 | 69 | - Example (500 Hz USB keyboard): 70 | 71 | .. code-block:: sh 72 | 73 | $ sudo vim /etc/default/grub 74 | GRUB_CMDLINE_LINUX_DEFAULT="usbhid.kbpoll=2" 75 | $ sudo grub-mkconfig -o /boot/grub/grub.cfg 76 | 77 | [4] 78 | 79 | Gamepads 80 | ~~~~~~~~ 81 | 82 | A gamepad is a game controller that usually has thumbsticks, triggers, and buttons. 83 | 84 | Top gamepads [1]: 85 | 86 | 1. Xbox 360 Controller 87 | 2. PS4 Controller 88 | 3. Xbox One Controller 89 | 4. PS3 Controller 90 | 5. Steam Controller 91 | 92 | Xbox Controllers 93 | ^^^^^^^^^^^^^^^^ 94 | 95 | The Linux kernel natively provides a ``xpad`` driver for wired original Xbox, Xbox 360, and Xbox One controllers. However, the Xbox One controller support conflicts with the new and improved ``xone`` driver. It is recommended to use ``xpad-noone`` instead of ``xpad`` to remove the overlapping support of Xbox One controllers. Otherwise, there were be problems with driver conflicts. [5] Bluetooth controllers natively work and do not require any additional setup. 96 | 97 | - Install ``xpad-noone`` and block the usage of ``xpad``. 98 | 99 | .. code-block:: sh 100 | 101 | $ sudo git clone https://github.com/medusalix/xpad-noone /usr/src/xpad-noone-1.0 102 | $ sudo dkms install -m xpad-noone -v 1.0 -k $(uname -r) 103 | $ echo -e "\nblacklist xpad\n" | sudo tee -a /etc/modprobe.d/xbox-controllers.conf 104 | $ sudo rmmod xpad 105 | $ sudo modprobe xpad-noone 106 | 107 | - Install the modern ``xone-dkms`` driver for handling Xbox One and Xbox Series controllers. 108 | 109 | - Arch Linux: 110 | 111 | .. code-block:: sh 112 | 113 | $ yay -S xone-dkms-git 114 | $ sudo modprobe xone-wired 115 | 116 | History 117 | ------- 118 | 119 | - `Latest `__ 120 | 121 | Bibliography 122 | ------------ 123 | 124 | 1. "Controller Gaming on PC." Steam Blog. September 25, 2018. Accessed August 17, 2021. https://steamcommunity.com/games/593110/announcements/detail/1712946892833213377 125 | 2. "USB 3.2 Speed Comparison & Drive Benchmark." Everything USB. November 2019. Accessed August 25, 2021. https://www.everythingusb.com/speed.html 126 | 3. "USB 3, USB 4, Thunderbolt, & USB-C --- everything you need to know." AppleInsider. August 24, 2020. Accessed August 25, 2021. https://appleinsider.com/articles/20/08/24/usb-3-usb-4-thunderbolt-usb-c----everything-you-need-to-know 127 | 4. "Mouse polling rate." Arch Wiki. January 25, 2022. Accessed February 11, 2022. https://wiki.archlinux.org/title/mouse_polling_rate 128 | 5. "Added information about xpad-noone #15." GitHub medusalix/xone. August 27, 2022. Accessed February 16, 2023. https://github.com/medusalix/xone/pull/15 129 | -------------------------------------------------------------------------------- /src/computer_hardware/desktops.rst: -------------------------------------------------------------------------------- 1 | Desktops 2 | ======== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Used Workstations 7 | ----------------- 8 | 9 | Introduction 10 | ~~~~~~~~~~~~ 11 | 12 | Used workstations can be found for cheap (under $100). Look for workstations that have an Intel Xeon processor (E5-1650 v2 or newer). Those high-end processors still work well for productivity and gaming today. [3] 13 | 14 | Brand and series [1][2]: 15 | 16 | - Dell Precision 17 | 18 | - Example models: T3600 or T600. 19 | 20 | - HP Z 21 | 22 | - There are two variants: the normal desktop "tower" and the "small form factor" (SSF). The tower normally has twice as much wattage as the SSF and includes a 6-pin PCIe power cable for a GPU. 23 | - Example models: Z420, Z440, Z620, or Z820. 24 | 25 | - Lenovo ThinkStation 26 | 27 | - Example model: S30. 28 | 29 | Recommended Upgrades 30 | ~~~~~~~~~~~~~~~~~~~~ 31 | 32 | - RAM 33 | 34 | - At least 16 GB of RAM is recommended for modern gaming. Get a complete kit of RAM as workstations do not always allow using different variants of RAM sticks. 35 | - Workstation and server processors normally require error correction code (ECC) RAM. 36 | 37 | - GPU = Due to limited wattage, consider getting a GPU that can be powered by `just the PCIe slot `__. 38 | - CPU = Find which processors the workstation support. The selection may be smaller than what the motherboard typically supports. Purchase the best possible CPU that is compatible and the current cooling system supports. For the best results, swap out the CPU for one that uses the same wattage. 39 | - NVMe drive = NVMe drives provide the fastest performance. For older workstations that do not have NVMe, a PCIe slot adapter can be purchased. Then the drive can be set up as a secondary drive for applications and games. 40 | - Network interface card = A PCIe 2.5 Gbps Ethernet or Wi-Fi 6E adapter can be purchased to increase the network connection speed. 41 | 42 | [5][6] 43 | 44 | History 45 | ------- 46 | 47 | - `Latest `__ 48 | 49 | Bibliography 50 | ------------ 51 | 52 | 1. "This $69 Gaming PC is INCREDIBLE." YouTube Linus Tech Tips. September 13, 2022. Accessed August 9, 2023. https://www.youtube.com/watch?v=xTAzwKiQ7Ns 53 | 2. "Refurbished workstations are insane deal for gaming on a budget." Reddit r/lowendgaming. February 16, 2020. Accessed August 9, 2023. https://www.reddit.com/r/lowendgaming/comments/f4xe8u/refurbished_workstations_are_insane_deal_for/ 54 | 3. "Xeon e5-1650 Old workstation as Gaming Pc." Reddit r/buildapc. May 16, 2023. Accessed August 9, 2023. https://www.reddit.com/r/buildapc/comments/y1idf7/xeon_e51650_old_workstation_as_gaming_pc/ 55 | 4. "Power Supply; Power Supply Specifications - HP Z240 Maintenance And Service Manual." ManualsLib. Accessed August 9, 2023. https://www.manualslib.com/manual/1036008/Hp-Z240.html?page=66 56 | 5. "Can’t afford a Gaming PC? This one's $169." YouTube Linus Tech Tips. October 15, 2022. Accessed August 9, 2023. https://www.youtube.com/watch?v=YLC9rZ2e0Ms 57 | 6. "10 killer PC upgrades that are shockingly cheap." PCWorld. December 28, 2021. Accessed August 9, 2023. https://www.pcworld.com/article/415985/10-killer-pc-upgrades-that-are-shockingly-cheap.html 58 | -------------------------------------------------------------------------------- /src/computer_hardware/electrical_equipment.rst: -------------------------------------------------------------------------------- 1 | Electrical Equipment 2 | ==================== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Wires 7 | ----- 8 | 9 | Use-Cases 10 | ~~~~~~~~~ 11 | 12 | There are the three use-cases for electrical wires [3]: 13 | 14 | - Hot or Live = This is the source of electricity. Handle this wire with caution. It is recommended to disable the power source, if possible, when handling this wire. 15 | - Neutral = This completes an electrical circuit. It will only have power if a hot/live wire is connected. 16 | - Ground = For when the power may be unstable, power is redirected through this wire and literally into the ground to dissipate the energy. 17 | 18 | Types 19 | ~~~~~ 20 | 21 | Wires have two physical types [4]: 22 | 23 | - Solid = A single piece of wire. 24 | 25 | - Easier to solder. 26 | - Less flexible. 27 | - Easier to break. 28 | - Easier to insert into holes and terminal connectors. 29 | 30 | - Stranded = A collection of smaller wires combined. 31 | 32 | - Harder to solder. 33 | - More flexible. 34 | - Harder to break. 35 | - Harder to insert into holes and terminal connectors. 36 | 37 | Gauges 38 | ~~~~~~ 39 | 40 | A gauge is how thick a wire is. The lower the number, the bigger the thickness. Here are recommendations for what gauge wire to use based on the project: 41 | 42 | - 22 43 | 44 | - Breadboard, Arduino, Raspberry Pi, and other single-board devices. [4] 45 | 46 | - 18 47 | 48 | - House lights. [5] 49 | - Small appliances. [5] 50 | - Speakers. [6] 51 | 52 | - 14 53 | 54 | - House in-wall electrical wiring. [4] 55 | - Speakers that require high power consumption and/or long wires. [6] 56 | 57 | Colors 58 | ~~~~~~ 59 | 60 | Each country has a different standard for the purpose of each colored wire. In the United States of America, these are the standards [2]: 61 | 62 | - Hot 63 | 64 | - **Black** 65 | - Blue 66 | - Brown 67 | - Yellow 68 | - Red = High voltage up to 240 volts. 69 | - Orange = Very high voltage up to 480 volts. 70 | 71 | - Neutral 72 | 73 | - **White** = High voltage up to 240 volts. 74 | - Grey = Very high voltage up to 480 volts. 75 | 76 | - Ground 77 | 78 | - **Green** 79 | - Bare wire (no covering) 80 | 81 | Relays 82 | ------ 83 | 84 | A relay is a switch that controls power being sent through a wire or circuit. It is either normally open (NO) or normally closed (NC) when there is power sent through a contact in relay. When there is no power through a contact, a NO gate will turn off and a NC gate will turn on. 85 | 86 | There are two types of relays: electromechanical relays (EMR) and solid-state relays (SSR). EMR uses magnets to move a physical switch. SSR uses circuits to direct electricity. 87 | 88 | EMR: 89 | 90 | - State of the relay is more reliable. 91 | 92 | - It is either on or off. 93 | 94 | - Requires more power to change the state. 95 | - Slower switching. 96 | - More likely to break. 97 | - Replaceable parts. 98 | - Moving parts. 99 | 100 | SSR: 101 | 102 | - State of the relay is less reliable. 103 | 104 | - It is somewhere between on and off but leans towards one or the other. 105 | 106 | - Requires less power to change the state. 107 | - Faster switching. 108 | - Less likely to break. 109 | - Non-replaceable parts. 110 | - No moving parts. 111 | 112 | [1] 113 | 114 | History 115 | ------- 116 | 117 | - `Latest `__ 118 | 119 | Bibliography 120 | ------------ 121 | 122 | 1. "How Relays Work." Galco. Accessed September 24, 2021. https://www.galco.com/comp/prod/relay.htm 123 | 2. "Wiring Color Codes Chapter 2 - Color Codes." All About Circuits Electrical Textbook. Accessed May 8, 2022. https://www.allaboutcircuits.com/textbook/reference/chpt-2/wiring-color-codes-infographic/ 124 | 3. "Electrical Wiring Tips: What is Hot, Neutral, and Ground." Roman Electric. Accessed May 8, 2022. https://romanelectrichome.com/electrical-wiring-tips/ 125 | 4. "Stock Up on Wire for Your Electronics Projects." dummies. March 26, 2016. Accessed May 8, 2022. https://www.dummies.com/article/technology/electronics/general-electronics/stock-up-on-wire-for-your-electronics-projects-180328/ 126 | 5. "Fix a Lamp Cord." Family Handyman. August 28, 2019. Accessed May 8, 2022. https://www.familyhandyman.com/project/fix-a-lamp-cord/ 127 | 6. "What Size Speaker Wire Is Right? The Right Gauge, Type, And More." Sound Certified. April 10, 2022. Accessed May 8, 2022. https://soundcertified.com/what-size-speaker-wire-guide/ 128 | -------------------------------------------------------------------------------- /src/computer_hardware/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Computer Hardware 4 | 5 | accessories 6 | desktops 7 | electrical_equipment 8 | graphics_cards 9 | laptops 10 | monitors 11 | networking 12 | power_supply_units 13 | processors 14 | ram 15 | storage_devices 16 | webcams 17 | -------------------------------------------------------------------------------- /src/computer_hardware/laptops.rst: -------------------------------------------------------------------------------- 1 | Laptops 2 | ======= 3 | 4 | .. contents:: Table of Contents 5 | 6 | Brands 7 | ------ 8 | 9 | Brands that provide Linux pre-installed: 10 | 11 | - `Dell `__ = RHEL, SLED, and Ubuntu. 12 | - `Lenovo `__ = `Fedora `__, RHEL, SLED, and Ubuntu. 13 | - `Star Labs `__ = elementary OS, Linux Mint, Manjaro, MX Linux, Ubuntu, or Zorin OS. 14 | - `System76 `__ = Pop!_OS and Ubuntu. 15 | - `TUXEDO Computers `__ = Manjaro, openSUSE, TUXEDO_OS, or Ubuntu. 16 | 17 | Brands that provide Linux hardware support but do not pre-install an operating system: 18 | 19 | - `Framework `__ = `Fedora `__, `Linux Mint `__, `Manjaro `__, and `Ubuntu `__. 20 | 21 | Graphics Cards 22 | -------------- 23 | 24 | NVIDIA 25 | ~~~~~~ 26 | 27 | For the best experience, get a laptop with at least an `Intel Coffee Lake (Intel Core >= 9000 series) CPU `__ and a `NVIDIA Turing (GeForce RTX >= 2000 series) GPU `__. These are the minimum requirements for automatic power management of the graphics card which will greatly increase battery life. The integrated Intel GPU is used until an application is specifically ran with offloading to the NVIDIA GPU. [1] 28 | 29 | Battery 30 | ------- 31 | 32 | There are a few popular battery management utilities for Linux that are used to extend the battery life of a laptop. The most popular options are `auto-cpufreq `__ and `TLP `__. Both programs will automatically change power profiles based on the current usage of the portable computer. 33 | 34 | ``auto-cpufreq`` is preferred as it has more features such as a turbo mode to increase the processor frequency/speed. These two programs are not compatible with each other. 35 | 36 | Install: 37 | 38 | - Arch Linux: 39 | 40 | .. code-block:: sh 41 | 42 | $ yay -S auto-cpufreq 43 | 44 | - Other: 45 | 46 | .. code-block:: sh 47 | 48 | $ git clone https://github.com/AdnanHodzic/auto-cpufreq.git 49 | $ cd ./auto-cpufreq/ 50 | $ sudo ./auto-cpufreq-installer 51 | 52 | Enable and start the service: 53 | 54 | .. code-block:: sh 55 | 56 | $ sudo systemctl enable --now auto-cpufreq 57 | 58 | [2] 59 | 60 | Cooling 61 | ------- 62 | 63 | A comparison was done between three different types of cooling methods for a laptop. These are differences in temperature (celsius) between each cooling method versus having the laptop on a desk. Using a cooling pad can provide the best results but, on average, a laptop stand is usually the best. [3] 64 | 65 | .. csv-table:: 66 | :header: Method, Min, Average, Max 67 | :widths: 20, 20, 20, 20 68 | 69 | Cooling Pad, -1.0, 3.4, 11 70 | Vacuum Cooler, -1.0, 3.4, 7.0 71 | Laptop Stand, 0.0, 3.6, 5.0 72 | 73 | History 74 | ------- 75 | 76 | - `Latest `__ 77 | 78 | Bibliography 79 | ------------ 80 | 81 | 1. "Chapter 22. PCI-Express Runtime D3 (RTD3) Power Management." NVIDIA Accelerated Linux Graphics Driver README and Installation Guide. Accessed December 30, 2020. https://us.download.nvidia.com/XFree86/Linux-x86_64/455.45.01/README/dynamicpowermanagement.html 82 | 2. "AdnanHodzic/auto-cpufreq." GitHub. January 9, 2022. Accessed February 5, 2022. https://github.com/AdnanHodzic/auto-cpufreq 83 | 3. "The ULTIMATE Laptop Cooling Comparison - Pad vs Vacuum vs Stand." YouTube - Jarrod'sTech. March 23, 2020. Accessed December 20, 2022. https://www.youtube.com/watch?v=tXvKiy65pwg 84 | -------------------------------------------------------------------------------- /src/computer_hardware/networking.rst: -------------------------------------------------------------------------------- 1 | Networking 2 | ========== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Networking hardware commonly includes switches, routers, wireless access points, and/or firewalls. 7 | 8 | Wi-Fi 9 | ----- 10 | 11 | Brands 12 | ~~~~~~ 13 | 14 | These are Wi-Fi chipset manufacturers from order of best to worst Linux support [2]: 15 | 16 | 1. Mediatek 17 | 2. Qualcomm 18 | 3. Intel 19 | 4. (Other brands) 20 | 5. Realtek 21 | 22 | `morrownr `__ created a `USB Wi-Fi guide `__ that showcases consumer Wi-Fi devices that use chipsets that are natively supported by the Linux kernel. 23 | 24 | Broadcom 25 | ^^^^^^^^ 26 | 27 | Broadcom has many different Linux kernel drivers. ``brcm80211`` is the official open source driver that Broadcom contributed directly to the Linux kernel. The proprietary driver ``wl`` provides better and more stable support. [5] 28 | 29 | - Install the ``wl`` driver. 30 | 31 | - Arch Linux [5]: 32 | 33 | .. code-block:: sh 34 | 35 | $ sudo pacman -S linux-headers broadcom-wl 36 | 37 | - Debian (non-free repository) [6]: 38 | 39 | .. code-block:: sh 40 | 41 | $ sudo apt-get install linux-image-$(uname -r) linux-headers-$(uname -r) broadcom-sta-dkms 42 | 43 | - Fedora (UnitedRPMs repository) [7]: 44 | 45 | .. code-block:: sh 46 | 47 | $ sudo dnf install kernel-devel kernel-headers broadcom-wl-dkms 48 | 49 | - Blacklist all of the open source drivers and conflicting drivers. [5][6][8] 50 | 51 | .. code-block:: sh 52 | 53 | $ sudo -E ${EDITOR} /etc/modprobe.d/broadcom.conf 54 | 55 | :: 56 | 57 | blacklist b43 58 | blacklist b43legacy 59 | blacklist bcm43xx 60 | blacklist bcma 61 | blacklist brcm80211 62 | blacklist brcmsmac 63 | blacklist brcmfmac 64 | blacklist brcmutil 65 | blacklist ndiswrapper 66 | blacklist ssb 67 | blacklist tg3 68 | 69 | - Configure the ``wl`` driver to load on boot. 70 | 71 | .. code-block:: sh 72 | 73 | $ sudo -E ${EDITOR} /etc/modules-load.d/broadcom.conf 74 | 75 | :: 76 | 77 | wl 78 | 79 | - Reboot. 80 | 81 | Speed 82 | ~~~~~ 83 | 84 | These are the maximum speeds for each Wi-Fi standard [3][4]: 85 | 86 | .. csv-table:: 87 | :header: Consumer Name, IEEE Name, Specification Speed (Mbps), Real-World Speed (Mbps), Real-World Speed (MBps) 88 | :widths: 20, 20, 20, 20, 20 89 | 90 | Wi-Fi 1, 802.11b, 11, 5.5, 0.7 91 | Wi-Fi 2, 802.11a, 54, 20, 2.5 92 | Wi-Fi 3, 802.11g, 54, 20, 2.5 93 | Wi-Fi 4, 802.11n, 600, 100, 12.5 94 | Wi-Fi 5, 802.11ac, 1300, 740, 92.5 95 | Wi-Fi 6, 802.11ax (5 GHz), 10000, 1150, 143.8 96 | Wi-Fi 6E, 802.11ax (6 GHz), 10000, 1800, 225.0 97 | 98 | Virtualization 99 | -------------- 100 | 101 | GNS3 102 | ~~~~ 103 | 104 | The Graphical Network Simulator 3 (GNS3) is a free and open source software for setting up virtual lab environments consisting of switches and routers. Virtual images are provided by most of the major network manufacturers that can be used with GNS3. [1] 105 | 106 | - `Arista's vEOS `__ 107 | - `Cisco IOS `__ 108 | - `Junos vQFX `__ 109 | - `VyOS `__ 110 | 111 | - `VyOS GNS3 Guide `__ 112 | 113 | The `GNS3 Marketplace `__ provides many templates that mirror configurations and hardware that production devices use. 114 | 115 | History 116 | ------- 117 | 118 | - `Latest `__ 119 | - `< 2022.10.01 `__ 120 | - `< 2019.01.01 `__ 121 | 122 | Bibliography 123 | ------------ 124 | 125 | 1. "[GNS3] Frequently Asked Questions." GNS3. Accessed May 7, 2018. https://gns3.com/software/faq 126 | 2. "Need Your Help: We need to let Comfast know what we think about multi-state adapters... #70." GitHub morrownr/USB-WiFi. July 27, 2022. Accessed September 27, 2022. https://github.com/morrownr/USB-WiFi/issues/70#issuecomment-1196277552 127 | 3. "How Fast Is a Wi-Fi Network?" Lifewire. June 16, 2021. Accessed September 27, 2022. https://www.lifewire.com/how-fast-is-a-wifi-network-816543 128 | 4. "Wi-Fi 6 vs Wi-Fi 6e: What's the difference?" Tom's Guide. September 19, 2022. Accessed October 29, 2022. https://www.tomsguide.com/face-off/wi-fi-6-vs-wi-fi-6e-whats-the-difference 129 | 5. "Broadcom wireless." ArchWiki. October 21, 2022. Accessed November 3, 2022. https://wiki.archlinux.org/title/broadcom_wireless 130 | 6. "wl." Debian Wiki. February 15, 2022. Accessed November 3, 2022. https://wiki.debian.org/wl 131 | 7. "Step-by-step – broadcom-wl-dkms Fedora 35 Installation." Step by Step Linux Tutorials for Beginners & Pros. October 6, 2021. Accessed November 3, 2022. https://tutorialforlinux.com/2021/10/06/step-by-step-broadcom-wl-dkms-fedora-35-installation/2/ 132 | 8. "WifiDocs/Driver/bcm43xx." Official Ubuntu Documentation. December 5, 2017. Accessed November 3, 2022. https://help.ubuntu.com/community/WifiDocs/Driver/bcm43xx 133 | -------------------------------------------------------------------------------- /src/computer_hardware/power_supply_units.rst: -------------------------------------------------------------------------------- 1 | Power Supply Units (PSUs) 2 | ========================= 3 | 4 | .. contents:: Table of Contents 5 | 6 | Cables 7 | ------ 8 | 9 | Every cable a PSU provides is rated to provide a maximum amount of wattage. 10 | 11 | .. csv-table:: 12 | :header: Power Source, Wattage 13 | :widths: 20, 20 14 | 15 | 4-pin CPU, 168 16 | 8-pin CPU, 336 [1] 17 | 6-pin PCIe cable, 75 18 | 8-pin PCIe cable, 150 [2] 19 | 12VHPWR PCIe cable, 600 [3] 20 | SATA, 54 21 | Molex, 156 [4] 22 | 23 | Adapters 24 | ~~~~~~~~ 25 | 26 | Here are a list of safe adapters to use. Providing lower wattage than what is expected can lead to a fire. 27 | 28 | - 2x Molex to 1x 4-pin CPU. 29 | - 2x SATA to 1x 6-pin GPU. 30 | - 1x Molex to 1x 6-pin GPU. 31 | - 1x Molex to 1x 8-pin GPU. 32 | - 1x 8-pin GPU to 1x 6-pin GPU. 33 | 34 | History 35 | ------- 36 | 37 | - `Latest `__ 38 | 39 | Bibliography 40 | ------------ 41 | 42 | 1. "Why Your Motherboard Has CPU Power 1 and CPU Power 2." MakeUseOf. April 20, 2023. Accessed August 8, 2023. https://www.makeuseof.com/why-your-motherboard-has-cpu-power-1-cpu-power-2/ 43 | 2. "PCI-E 3.0 Slot Power." Overclock.net. August 2, 2013. Accessed August 8, 2023. https://www.overclock.net/threads/pci-e-3-0-slot-power.1414801/ 44 | 3. "PCIe Gen5 "12VHPWR" Connector to Deliver Up to 600 Watts of Power for Next-Generation Graphics Cards." TechPowerUp. October 11, 2021. Accessed August 8, 2023. https://www.techpowerup.com/287682/pcie-gen5-12vhpwr-connector-to-deliver-up-to-600-watts-of-power-for-next-generation-graphics-cards 45 | 4. "Maximum Safe Wattage of PSU Cables." GPU Mining Resources. March 15, 2019. https://www.gpuminingresources.com/p/psu-cables.html 46 | -------------------------------------------------------------------------------- /src/computer_hardware/processors.rst: -------------------------------------------------------------------------------- 1 | Processors 2 | ========== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Simultaneous Multithreading (SMT) 7 | --------------------------------- 8 | 9 | SMT, also known as Hyper-Threading Technology (HTT) on Intel processors, allows each processor to act as two logical processors. For example, a processor with 4 physical cores will have a total of 8 logical threads. A processor with SMT enabled will have around a 30% increase in performance. [1] 10 | 11 | Recommended Number of Cores 12 | --------------------------- 13 | 14 | Depending on the use-case, these are the recommended total number of processor cores to have. 15 | 16 | Gaming [2]: 17 | 18 | .. csv-table:: 19 | :header: Use-case, Cores 20 | :widths: 20, 20 21 | 22 | Very old games (Windows XP), 2 23 | Old games (Windows 7), 4 24 | Modern games (Windows 10), 6 25 | 26 | Video editing [3][4]: 27 | 28 | .. csv-table:: 29 | :header: Resolution, Cores 30 | :widths: 20, 20 31 | 32 | 720p, 4 33 | 1080p, 6 34 | 4K, 8 35 | 8K, 10 36 | 37 | Machine learning (ML) [5]: 38 | 39 | .. csv-table:: 40 | :header: ML Workload, Cores 41 | :widths: 20, 20 42 | 43 | Minimum, 16 44 | Recommended, 32 45 | Maximum, 64 46 | 47 | History 48 | ------- 49 | 50 | - `Latest `__ 51 | 52 | Bibliography 53 | ------------ 54 | 55 | 1. "How to Determine the Effectiveness of Hyper-Threading Technology with an Application." Intel Development Topics & Technologies. April 28, 2011. Accessed September 2, 2020. https://software.intel.com/content/www/us/en/develop/articles/how-to-determine-the-effectiveness-of-hyper-threading-technology-with-an-application.html 56 | 2. "How Many CPU Cores Do I Need For Gaming?" GamingScan. January 10, 2022. Accessed September 29, 2022. https://www.gamingscan.com/how-many-cores-for-gaming/ 57 | 3. "How to choose the right computer for video editing: 4 key specs to check." Videomaker. Accessed September 29, 2022. https://www.videomaker.com/buyers-guide/how-to-choose-the-right-video-editing-workstation/ 58 | 4. "How many processing cores do you need in a video editing computer?" ProMAX. September 26, 2019. Accessed September 29, 2022. https://www.promax.com/blog/how-many-processing-cores-do-you-need-in-a-video-editing-computer 59 | 5. "Hardware Recommendations for Machine Learning & AI." Puget Systems. Accessed September 29, 2022. https://www.pugetsystems.com/recommended/Recommended-Systems-for-Machine-Learning-AI-174/Hardware-Recommendations 60 | -------------------------------------------------------------------------------- /src/computer_hardware/ram.rst: -------------------------------------------------------------------------------- 1 | Random Access Memory (RAM) 2 | ========================== 3 | 4 | Recommended Size 5 | ---------------- 6 | 7 | Depending on the use-case, these are the recommended total size of system RAM to have. 8 | 9 | Gaming [1][4]: 10 | 11 | .. csv-table:: 12 | :header: Use-case, RAM (GB) 13 | :widths: 20, 20 14 | 15 | Very old games (Windows XP), 4 16 | Old games (Windows 7), 8 17 | Modern games (Windows 10), 16 18 | 19 | Video editing [2]: 20 | 21 | .. csv-table:: 22 | :header: Resolution, RAM (GB) 23 | :widths: 20, 20 24 | 25 | 720p, 8 26 | 1080p, 16 27 | 4K, 32 28 | 8K, 64 29 | 30 | Machine learning (ML) [3]: 31 | 32 | .. csv-table:: 33 | :header: ML Workload, RAM (GB) 34 | :widths: 20, 20 35 | 36 | Minimum, 32 37 | Recommended, 64 38 | Maximum, 128 39 | 40 | - The RAM in a system for ML should be at least twice as much as the VRAM on the GPU. It is recommended to also round up to the closest interval of 32 GB of RAM. [3] 41 | 42 | History 43 | ------- 44 | 45 | - `Latest `__ 46 | 47 | Bibliography 48 | ------------ 49 | 50 | 1. "Is Buying More RAM a WASTE for Gamers? (2022)." YouTube - Linus Tech Tips. June 16, 2022. Accessed July 13, 2022. https://www.youtube.com/watch?v=H19_JKw4QN4 51 | 2. "How Much Memory Do You Need for Video Editing?" Kingston Blog. February 2021. Accessed July 13, 2022. https://www.kingston.com/en/blog/pc-performance/how-much-memory-needed-for-video-editing 52 | 3. "Hardware Recommendations for Machine Learning & AI." Puget Systems. Accessed September 7, 2022. https://www.pugetsystems.com/recommended/Recommended-Systems-for-Machine-Learning-AI-174/Hardware-Recommendations 53 | 4. "How Much Memory Do You Need for Gaming?" July, 2021. Accessed September 29, 2022. https://www.kingston.com/en/blog/gaming/how-much-memory-for-gaming 54 | -------------------------------------------------------------------------------- /src/computer_hardware/storage_devices.rst: -------------------------------------------------------------------------------- 1 | Storage Devices 2 | =============== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Types and Speed 7 | --------------- 8 | 9 | Hard disk drives (HDDs): 10 | 11 | .. csv-table:: 12 | :header: Rotations Per Minute (RPM), Max Speed (MB/s), Connector 13 | :widths: 20, 20, 20 14 | 15 | 5400, 110, IDE or SATA 16 | 7200, 145, IDE or SATA 17 | 10000, 200, SATA or SAS 18 | 15000, 300, SATA or SAS 19 | 20 | Solid state drives (SSDs): 21 | 22 | .. csv-table:: 23 | :header: Name, Max Speed (MB/s), Connector 24 | :widths: 20, 20, 20 25 | 26 | SSD, 500, SATA or SAS 27 | NVMe, 3000, M.2 SATA 28 | NVMe (PCIe 4.0), 5000, M.2 SATA (PCIe 4.0) 29 | 30 | Secure Digital (SD) cards [3]: 31 | 32 | .. csv-table:: 33 | :header: Name, Max Speed (MB/s) 34 | :widths: 20, 20 35 | 36 | Default Speed, 12.5 37 | High Speed, 25 38 | UHS-I, 100 39 | UHS-II, 300 40 | UHS-III, 600 41 | SD Express, 4000 42 | 43 | Average Size 44 | ------------ 45 | 46 | Here are the average storage drive sizes for each era of Windows operating systems by the time the next Windows release came out. 47 | 48 | .. csv-table:: 49 | :header: Windows, Size (GB) 50 | :widths: 20, 20 51 | 52 | Windows XP (2007), 100 [4] 53 | Windows 7 (2012), 700 [5] 54 | Windows 10 (2021), 1000 [6] 55 | 56 | HDD Magnetic Recording 57 | ---------------------- 58 | 59 | Magnetic hard drives use one of two different technologies for writing data: Conventional Magnetic Recording (CMR) or Shingled Magnetic Recording (SMR). CMR provides lower storage space but significantly faster write speeds. This is ideal for most use cases. SMR provides higher storage space but significantly slower write speeds. It should only be used for long-term storage. It is known to be extremely slow for RAID and NAS usage. [1] 60 | 61 | NAND Flash Types 62 | ---------------- 63 | 64 | All SSDs (including NVMe) use a specific type of NAND flash: single-level cell (SLC), multi-level cell (MLC), triple-level (TLC), quad-level cell (QLC), or penta-level cell (PLC). These describe how many bits are stored in each cell. A higher amount of bits leads to higher storage capacity, lower the reliability (if a cell dies then more bits are lost), lower life span (more writes happen on each cell), and slower speed (more bits need to be written to store data). The most common type in 2019 is TLC. [2] 65 | 66 | Power Loss Protection (PLP) 67 | --------------------------- 68 | 69 | PLP is a feature found in enterprise-grade drives. [7] It prevents file system corruption due to a power outage. There are two types of PLP [8]: 70 | 71 | - Firmware = The DRAM cache stores the mapping table and will finish writing data once the drive has been turned on again. 72 | - Hardware = Capacitors on the drive keep it running so DRAM cache can safely finish writing to the drive before turning the drive off. 73 | 74 | History 75 | ------- 76 | 77 | - `Latest `__ 78 | 79 | Bibliography 80 | ------------ 81 | 82 | 1. "Buyer beware—that 2TB-6TB “NAS” drive you’ve been eyeing might be SMR." Ars Technica. April 17, 2020. Accessed August 12, 2020. https://arstechnica.com/gadgets/2020/04/caveat-emptor-smr-disks-are-being-submarined-into-unexpected-channels/ 83 | 2. "Multi-Layer SSDs: What Are SLC, MLC, TLC, QLC, and PLC?." How-To Geek. October 28, 2019. Accessed August 12, 2020. https://www.howtogeek.com/444787/multi-layer-ssds-what-are-slc-mlc-tlc-qlc-and-mlc/ 84 | 3. "Bus Speed (Default Speed/High Speed/UHS/SD Express)." SD Assocation. Accessed August 2, 2021. https://www.sdcard.org/developers/sd-standard-overview/bus-speed-default-speed-high-speed-uhs-sd-express/ 85 | 4. "2007 HDD Rundown: Can High Capacities Meet High Performance?" Tom's Hardware. January 16, 2007. Accessed August 7, 2023. https://www.tomshardware.com/reviews/2007-hdd-rundown,1522.html 86 | 5. "Average capacity of Seagate and Western Digital hard disk drives (HDDs) worldwide from 3rd quarter 2011 to 1st quarter 2016." Statista. May 12, 2016. Accessed August 7, 2023. https://www.statista.com/statistics/751847/worldwide-seagate-western-digital-average-hard-drive-capacity/ 87 | 6. "Client SSDs: Samsung Retains No.1 Spot, SSDs Outsell HDDs by 2.6x." Tom's Hardware. August 20, 2021. Accessed August 7, 2023. https://www.tomshardware.com/news/client-ssds-outsell-client-hdds-by-2-6-times-in-q2 88 | 7. "Power loss protection (PLP)." Samsung_SSD_845DC_05_Power_loss_protection_PLP.pdf. 2014. Accessed August 9, 2023. https://www.kingston.com/en/blog/servers-and-data-centers/ssd-power-loss-protection 89 | 8. "A Closer Look At SSD Power Loss Protection." Kingston Blog. March, 2019. Accessed August 9, 2023. https://download.semiconductor.samsung.com/resources/others/Samsung_SSD_845DC_05_Power_loss_protection_PLP.pdf 90 | -------------------------------------------------------------------------------- /src/computer_hardware/webcams.rst: -------------------------------------------------------------------------------- 1 | Webcams 2 | ======= 3 | 4 | .. contents:: Table of Contents 5 | 6 | DSLR 7 | ---- 8 | 9 | Photos 10 | ~~~~~~ 11 | 12 | For photos, use the `Entangle `__ application. The DSLR needs to be connected to the computer via a USB cable and must NOT be mounted. 13 | 14 | Videos 15 | ~~~~~~ 16 | 17 | The swiss-army-knife `Open Broadcaster Software (OBS) Studio `__ provides a cross-platform way to stream DSLR output and use it for video recording and online conferencing. [1] This guide covers how to set it up for Arch Linux. Fedora currently has issues with compilation and does not have an official build available. [2] 18 | 19 | OBS < 26.1 requires this plugin to enable the "virtual camera" feature that the Windows version of OBS has built-in. It is shipped as part of OBS Studio 26.1. 20 | 21 | .. code-block:: sh 22 | 23 | $ yay -S obs-v4l2sink 24 | 25 | All versions of OBS will require the ``v4l2loopback`` kernel module for faking a webcam device. The gPhoto plugin for OBS is required to stream the video from the DSLR itself. 26 | 27 | .. code-block:: sh 28 | 29 | $ yay -S obs-gphoto v4l2loopback-dkms 30 | 31 | Set the required kernel module options [3]: 32 | 33 | - video_nr = The number to use for the ``/dev/video`` device name. Required for streaming more than one source. The default is ``/dev/video0``. 34 | - card_label = A nickname for the virtual webcam. Video conferencing software will use this as one of the possible input devices. 35 | - exclusive_caps=1 = Required for video conferencing software to detect the device as a webcam. 36 | 37 | .. code-block:: sh 38 | 39 | $ echo 'options v4l2loopback video_nr=0 card_label="vcam" exclusive_caps=1' | sudo tee /etc/modprobe.d/v4l2.conf 40 | 41 | Load the kernel module. 42 | 43 | .. code-block:: sh 44 | 45 | $ sudo modprobe v4l2loopback 46 | 47 | Set the kernel module to also load on boot. 48 | 49 | .. code-block:: sh 50 | 51 | $ echo 'v4l2loopback' | sudo tee /etc/modules-load.d/v4l2.conf 52 | 53 | In OBS, add a new Source: 54 | 55 | :: 56 | 57 | OBS Studio > Sources > + > gPhoto live preview capture 58 | 59 | The DSLR must NOT be mounted for the live preview to work. 60 | 61 | Create the virtual webcam device. It will now show up in online video conferencing software. [4] 62 | 63 | :: 64 | 65 | OBS Studio > Tools > v4l2sink > Start 66 | 67 | History 68 | ------- 69 | 70 | - `Latest `__ 71 | 72 | Bibliography 73 | ------------ 74 | 75 | 1. "OBS Studio." Open Broadcast Software. Accessed November 29, 2020. https://obsproject.com/ 76 | 2. "cant build on fedora 32 #42." GitHub CatxFish/obs-v4l2sink. September 18, 2020. Accessed November 29, 2020. https://github.com/CatxFish/obs-v4l2sink/issues/42 77 | 3. "Green-screen webcam on Linux." boombatower. April 14, 2020. Accessed November 29, 2020. https://blog.boombatower.com/2020/04/14/greenscreen-webcam-on-linux 78 | 4. "Has anyone successfully output from OBS to a live ZOOM conference on linux?" Open Broadcast Sofware Studio Support. October 3, 2020. Accessed November 29, 2020. https://obsproject.com/forum/threads/has-anyone-successfully-output-from-obs-to-a-live-zoom-conference-on-linux.117026/ 79 | -------------------------------------------------------------------------------- /src/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # Root Pages documentation build configuration file, created by 5 | # sphinx-quickstart on Sat Dec 23 12:50:38 2017. 6 | # 7 | # This file is execfile()d with the current directory set to its 8 | # containing dir. 9 | # 10 | # Note that not all possible configuration values are present in this 11 | # autogenerated file. 12 | # 13 | # All configuration values have a default; values that are commented out 14 | # serve to show the default. 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | # 20 | # import os 21 | # import sys 22 | # sys.path.insert(0, os.path.abspath('.')) 23 | 24 | 25 | # -- General configuration ------------------------------------------------ 26 | 27 | # If your documentation needs a minimal Sphinx version, state it here. 28 | # 29 | # needs_sphinx = '1.0' 30 | 31 | # Add any Sphinx extension module names here, as strings. They can be 32 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 33 | # ones. 34 | extensions = ['sphinx.ext.ifconfig', 35 | 'sphinx.ext.githubpages'] 36 | 37 | # Add any paths that contain templates here, relative to this directory. 38 | templates_path = ['_templates'] 39 | 40 | # The suffix(es) of source filenames. 41 | # You can specify multiple suffix as a list of string: 42 | # 43 | # source_suffix = ['.rst', '.md'] 44 | source_suffix = '.rst' 45 | 46 | # The master toctree document. 47 | master_doc = 'index' 48 | 49 | # General information about the project. 50 | project = 'Root Pages' 51 | # This will render out a sentence that starts with "Copyright None" 52 | copyright = 'None, Copyleft 2025, Luke Short. Documents licensed under GFDLv1.3' 53 | author = 'Luke Short' 54 | 55 | # The version info for the project you're documenting, acts as replacement for 56 | # |version| and |release|, also used in various other places throughout the 57 | # built documents. 58 | # 59 | # The short X.Y version. 60 | version = '2025.10.01-dev' 61 | # The full version, including alpha/beta/rc tags. 62 | #release = '' 63 | 64 | # The language for content autogenerated by Sphinx. Refer to documentation 65 | # for a list of supported languages. 66 | # 67 | # This is also used if you do content translation via gettext catalogs. 68 | # Usually you set "language" from the command line for these cases. 69 | language = 'en' 70 | 71 | # List of patterns, relative to source directory, that match files and 72 | # directories to ignore when looking for source files. 73 | # This patterns also effect to html_static_path and html_extra_path 74 | exclude_patterns = ["template.rst", "commands/template.rst"] 75 | 76 | # The name of the Pygments (syntax highlighting) style to use. 77 | pygments_style = 'sphinx' 78 | 79 | # If true, `todo` and `todoList` produce output, else they produce nothing. 80 | todo_include_todos = False 81 | 82 | 83 | # -- Options for HTML output ---------------------------------------------- 84 | 85 | # The theme to use for HTML and HTML Help pages. See the documentation for 86 | # a list of builtin themes. 87 | # 88 | html_theme = 'sphinx_rtd_theme' 89 | 90 | # Theme options are theme-specific and customize the look and feel of a theme 91 | # further. For a list of options available for each theme, see the 92 | # documentation. 93 | # 94 | html_theme_options = { 95 | 'sticky_navigation': True 96 | } 97 | 98 | # Add any paths that contain custom static files (such as style sheets) here, 99 | # relative to this directory. They are copied after the builtin static files, 100 | # so a file named "default.css" will overwrite the builtin "default.css". 101 | html_static_path = ['_static'] 102 | 103 | # Custom sidebar templates, must be a dictionary that maps document names 104 | # to template names. 105 | # 106 | # This is required for the alabaster theme 107 | # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars 108 | html_sidebars = { 109 | '**': [ 110 | 'localtoc.html', 111 | 'relations.html', # needs 'show_related': True theme option to display 112 | 'searchbox.html', 113 | ] 114 | } 115 | 116 | 117 | # -- Options for HTMLHelp output ------------------------------------------ 118 | 119 | # Output file base name for HTML help builder. 120 | htmlhelp_basename = 'RootPagesdoc' 121 | 122 | 123 | # -- Options for LaTeX output --------------------------------------------- 124 | 125 | latex_elements = { 126 | # The paper size ('letterpaper' or 'a4paper'). 127 | # 128 | # 'papersize': 'letterpaper', 129 | 130 | # The font size ('10pt', '11pt' or '12pt'). 131 | # 132 | # 'pointsize': '10pt', 133 | 134 | # Additional stuff for the LaTeX preamble. 135 | # 136 | # 'preamble': '', 137 | 138 | # Latex figure (float) alignment 139 | # 140 | # 'figure_align': 'htbp', 141 | } 142 | 143 | # Grouping the document tree into LaTeX files. List of tuples 144 | # (source start file, target name, title, 145 | # author, documentclass [howto, manual, or own class]). 146 | latex_documents = [ 147 | (master_doc, 'RootPages.tex', 'Root Pages Documentation', 148 | 'Luke Short', 'manual'), 149 | ] 150 | 151 | 152 | # -- Options for manual page output --------------------------------------- 153 | 154 | # One entry per manual page. List of tuples 155 | # (source start file, name, description, authors, manual section). 156 | man_pages = [ 157 | (master_doc, 'rootpages', 'Root Pages', 158 | [author], 1) 159 | ] 160 | 161 | 162 | # -- Options for Texinfo output ------------------------------------------- 163 | 164 | # Grouping the document tree into Texinfo files. List of tuples 165 | # (source start file, target name, title, author, 166 | # dir menu entry, description, category) 167 | texinfo_documents = [ 168 | (master_doc, 'RootPages', 'Root Pages', 169 | author, 'RootPages', 'A collection of quick and easy-to-reference tutorials, examples, and guides primarily for Linux and other UNIX-like systems', 170 | 'Miscellaneous'), 171 | ] 172 | 173 | 174 | 175 | # -- Options for Epub output ---------------------------------------------- 176 | 177 | # Bibliographic Dublin Core info. 178 | epub_title = project 179 | epub_author = author 180 | epub_publisher = author 181 | epub_copyright = copyright 182 | 183 | # The unique identifier of the text. This can be a ISBN number 184 | # or the project homepage. 185 | # 186 | # epub_identifier = '' 187 | 188 | # A unique identification for the text. 189 | # 190 | # epub_uid = '' 191 | 192 | # A list of files that should not be packed into the epub file. 193 | epub_exclude_files = ['search.html'] 194 | 195 | 196 | 197 | # -- Options for inernationalization ---------------------------------------------- 198 | locale_dirs = ['locale/'] 199 | gettext_compact = False 200 | -------------------------------------------------------------------------------- /src/graphics/gaming.rst: -------------------------------------------------------------------------------- 1 | Gaming 2 | ====== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Steam 7 | ----- 8 | 9 | Runtime 10 | ~~~~~~~ 11 | 12 | Steam provides a runtime that is a chroot of pre-installed Linux libraries required for Steam to work. Sometimes these libraries may not work as expected. There are different ways to configure how Steam will or will not use its own runtime. 13 | 14 | - Use the Steam runtime libraries. 15 | 16 | .. code-block:: sh 17 | 18 | $ STEAM_RUNTIME=1 steam 19 | 20 | - Use the system libraries and fall-back to Steam runtime libraries if they are missing on the system. 21 | 22 | .. code-block:: sh 23 | 24 | $ STEAM_RUNTIME=1 STEAM_RUNTIME_PREFER_HOST_LIBRARIES=1 steam 25 | 26 | - Use the system libraries. 27 | 28 | .. code-block:: sh 29 | 30 | $ STEAM_RUNTIME=0 steam 31 | 32 | [3] 33 | 34 | Flatpak 35 | ~~~~~~~ 36 | 37 | The Flatpak for Steam can mount external devices into the isolated environment. Mount points are not exposed in the Flatpak by default. [1] 38 | 39 | .. code-block:: sh 40 | 41 | $ flatpak override --user --filesystem= com.valvesoftware.Steam 42 | 43 | Proton (Steam Play) 44 | ~~~~~~~~~~~~~~~~~~~ 45 | 46 | Proton allows Windows games to run on Linux. A full list of games that are officially whitelisted and guaranteed to work can be found `here `__. Proton can be enabled for all games by going to ``Settings > Steam Play > Enable Steam Play for all other titles``. Compatibility will vary. [2] 47 | 48 | Steam Client Performance Tuning 49 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 50 | 51 | Various settings can be configured to make the Steam client use less system resources. 52 | 53 | - Steam > Settings 54 | 55 | - Friends & Chat 56 | 57 | - Sign in to friends whem Steam Client starts: No 58 | - Enable Animated Avatars & Animated Avatar Frames in your Friends List and Chat: No 59 | - Remember my open chats: No 60 | 61 | - Interface 62 | 63 | - Start Up Location: Library 64 | 65 | - Library 66 | 67 | - Low Bandwidth Mode: Yes 68 | - Low Performance Mode: Yes 69 | - Disable Community Content: Yes 70 | - Show game icons in the left column: No 71 | 72 | - Downloads 73 | 74 | - Enable Shader Pre-caching: No 75 | 76 | - Only disable this on devices that are not the Steam Deck running the official SteamOS. Valve provides pre-compiled shaders for it. 77 | - The graphics driver needs to support graphics pipeline library (GPL) for faster shader compilation that does not require pre-caching. 78 | 79 | - AMD = `Mesa 23.1.0 `__ 80 | - Intel = `Mesa 23.2.0 `__ 81 | - NVIDIA = `NVIDIA 515.49.10 `__ 82 | 83 | - In Game 84 | 85 | - Enable the Steam Overlay while in-game: Off 86 | 87 | Launch arguments for Steam: 88 | 89 | .. code-block:: sh 90 | 91 | $ steam -no-browser -nochatui -nofriendsui 92 | 93 | [4][5] 94 | 95 | Disable Steam Client Updates 96 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97 | 98 | Launch Steam with the following arguments to completely disable updates [6]: 99 | 100 | .. code-block:: sh 101 | 102 | $ steam -noverifyfiles -nobootstrapupdate -skipinitialbootstrap -norepairfiles -overridepackageurl 103 | 104 | Troubleshooting 105 | --------------- 106 | 107 | Error Messages 108 | ~~~~~~~~~~~~~~ 109 | 110 | Missing libraries when starting the Steam runtime: 111 | 112 | .. code-block:: sh 113 | 114 | $ steam-runtime 115 | Error: You are missing the following 32-bit libraries, and Steam may not run: 116 | 117 | Solution: 118 | 119 | - Run ``steam-runtime --reset`` to redownload the runtime libraries. 120 | 121 | History 122 | ------- 123 | 124 | - `Latest `__ 125 | - `< 2023.04.01 `__ 126 | - `< 2019.01.01 `__ 127 | 128 | Bibliography 129 | ------------ 130 | 131 | 1. "Frequently asked questions." flathub/com.valvesoftware.Steam. April 12, 2020. Accessed July 3, 2020. https://github.com/flathub/com.valvesoftware.Steam/wiki/Frequently-asked-questions 132 | 2. "A simple guide to Steam Play, Valve's technology for playing Windows games on Linux." GamingOnLinux. July 12, 2019. Accessed July 3, 2020. https://www.gamingonlinux.com/articles/14552 133 | 3. "Steam/Client troubleshooting." Gentoo Wiki. February 15, 2021. Accessed May 20, 2021. https://wiki.gentoo.org/wiki/Steam/Client_troubleshooting 134 | 4. "Why is steam using 27% CPU, and how can I stop it from using so much?" Reddit r/Steam. September 22, 2020. Accessed August 16, 2023. https://www.reddit.com/r/Steam/comments/ixi9ed/why_is_steam_using_27_cpu_and_how_can_i_stop_it/ 135 | 5. "How To Optimize Steam for Competitive Gaming." Forgeary. April 8, 2023. Accessed August 16, 2023. https://forgeary.com/optimize-steam/ 136 | 6. "Disabling Steam client auto-updates." Steam Help and Tips. December 15, 2019. Accessed October 6, 2023. https://steamcommunity.com/discussions/forum/1/1639788130289877816/ 137 | -------------------------------------------------------------------------------- /src/graphics/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Graphics 4 | 5 | desktop 6 | drivers 7 | gaming 8 | -------------------------------------------------------------------------------- /src/http/clustering.rst: -------------------------------------------------------------------------------- 1 | Clustering and High Availability 2 | ================================ 3 | 4 | .. contents:: Table of Contents 5 | 6 | Introduction 7 | ------------ 8 | 9 | Clustering is the concept of using a load balancer to distribute 10 | connections to multiple destinations. Three of the most common load 11 | balancing methods used in clustering are: 12 | 13 | - Round robin = Send each request to the next server in the pool. 14 | - Least connections = Send requests to the server with the least amount 15 | of connections. 16 | - Source IP = Send requests from a source to the same destination 17 | server. 18 | 19 | Ideally, high availability of services should also be of high importance 20 | to keep services working 100% of the time. [1] 21 | 22 | IP Virtual Server 23 | ----------------- 24 | 25 | The IP Virtual Server (IPVS) service utilizes the Linux kernel directly 26 | for load balancing. It is designed to be a simple load balancer for 27 | internal/private networks. [2] 28 | 29 | The only prerequisite for IPVS is that it requires the Linux system to 30 | be configured as a router (masquerading). This is an example of using 31 | the internal network 10.0.0.0/24 on the interface eth1 and forward 32 | requests to/from the public interface eth0. 33 | 34 | .. code-block:: sh 35 | 36 | $ sudo iptables -F 37 | $ sudo iptables -t nat -F 38 | $ sudo iptables -P INPUT ACCEPT 39 | $ sudo iptables -P OUTPUT ACCEPT 40 | $ sudo iptables -P FORWARD ACCEPT 41 | $ sudo iptables -A FORWARD -i eth1 -s 10.0.0.0/255.255.255.0 -j ACCEPT 42 | $ sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE 43 | 44 | IPVS is easily managed via the "ipvsadm" command. 45 | 46 | - View the current configuration. 47 | 48 | :: 49 | 50 | $ sudo ipvsadm -l 51 | 52 | - View more verbose information about current connections. [3] 53 | 54 | :: 55 | 56 | $ sudo ipvsadm -l -n --stats 57 | 58 | - Define the public IP address of the IPVS server (ex., 192.168.1.10), 59 | port (ex., :80 for HTTP), and then the type of load balancing (ex., 60 | "rr"). 61 | 62 | :: 63 | 64 | $ sudo ipvsadm -A -t : -s 65 | 66 | :: 67 | 68 | $ sudo ipvsadm -A -t 192.168.1.10:80 -s rr 69 | 70 | - Types of clustering schedulers for "-s": 71 | 72 | - rr = Round robin. 73 | - lc = Least connections. 74 | - sh = Source hash (source IP address). 75 | 76 | - Add a back-end server (-a), serving TCP connections (-t), using the 77 | specified public balancer IP and port, sending requests to the real 78 | back-end server's IP address (-r), and masquerade/NAT the requests 79 | (-m). 80 | 81 | :: 82 | 83 | $ sudo ipvsadm -a -t : -r -m 84 | 85 | :: 86 | 87 | $ sudo ipvsadm -a -t 192.168.1.10:80 -r 10.0.0.11 -m 88 | $ sudo ipvsadm -a -t 192.168.1.10:80 -r 10.0.0.12 -m 89 | 90 | - The configuration rules are automatically saved, but they can viewed 91 | in standard output. These rules can then be migrated or restored to 92 | an IPVS server. 93 | 94 | :: 95 | 96 | $ sudo ipvsadm {-S|--save} 97 | 98 | :: 99 | 100 | $ sudo ipvsadm {-R|--restore} 101 | 102 | - The entire configuration can be cleared at any time. [2] 103 | 104 | :: 105 | 106 | $ sudo ipvsadm {-C|--clear} 107 | 108 | History 109 | ------- 110 | 111 | - `Latest `__ 112 | - `< 2020.01.01 `__ 113 | - `< 2019.01.01 `__ 114 | - `< 2018.01.01 `__ 115 | 116 | Bibliography 117 | ------------ 118 | 119 | 1. "Nginx Load Balancing." Nginx. Accessed July 9, 2016. https://www.nginx.com/resources/admin-guide/load-balancer/ 120 | 2. "LVS-mini-HOWTO." Austintek. March, 2012. Accessed July 9, 2016. http://www.austintek.com/LVS/LVS-HOWTO/mini-HOWTO/LVS-mini-HOWTO.html 121 | 3. "Building a Load Balancer with LVS - Linux Virtual Server." Linux Admins. January, 2013. Accessed July 9, 2016. http://www.linux-admins.net/2013/01/building-load-balancer-with-lvs-linux.html 122 | -------------------------------------------------------------------------------- /src/http/cms.rst: -------------------------------------------------------------------------------- 1 | Content Management Systems (CMSs) 2 | ================================= 3 | 4 | .. contents:: Table of Contents 5 | 6 | Introduction 7 | ------------ 8 | 9 | A CMS provides a framework to create a website without having to code it from scratch or even knowing HTML. It automates the process of creating new webpages and can use different themes and plugins. Most CMSs have search engine optimizations (SEOs). The goal of a CMS is to make creating a website easy. [1] 10 | 11 | Hugo 12 | ---- 13 | 14 | Installation 15 | ~~~~~~~~~~~~ 16 | 17 | Install the ``hugo`` package. 18 | 19 | Create a new website: 20 | 21 | .. code-block:: sh 22 | 23 | $ hugo new site 24 | 25 | Unlike Jekyll, Hugo does not provide a default theme. Find and download a `Hugo theme from here `__. Extract it to the ``themes`` directory. Alternatively, use a git submodule to track the theme in a different repository. 26 | 27 | .. code-block:: sh 28 | 29 | $ git submodule add https:////.git themes/ 30 | 31 | Configure the theme to be used. 32 | 33 | .. code-block:: sh 34 | 35 | $ vim config.toml 36 | theme = "" 37 | 38 | Optionally create a new post on the website: 39 | 40 | .. code-block:: sh 41 | 42 | $ hugo new /.md 43 | $ vim content//.md 44 | --- 45 | title: "Example Post" 46 | date: 2021-01-01T12:00:00+00:00 47 | draft: false 48 | --- 49 | 50 | Generate and serve the static website: 51 | 52 | .. code-block:: sh 53 | 54 | $ hugo server 55 | 56 | Access the website via ``http://127.0.0.1:1313/``. 57 | 58 | [5] 59 | 60 | Configuration 61 | ~~~~~~~~~~~~~ 62 | 63 | All of the configuration is handled by the ``config.toml`` file. 64 | 65 | Settings: 66 | 67 | - baseURL (string) = The URL to the actual website. This is used when creating a static website with the ``hugo`` command (no arguments required). 68 | 69 | - When running ``hugo server``, this value is temporarily set to ``http://127.0.0.1:1313/``. 70 | - When building a static website, either change this to a URL or a ``file://`` path that points to the "public" folder. 71 | 72 | - languageCode (string) = The default language to use for the website. 73 | - **theme** (string) = The name of the theme to use. This will load up a theme ``themes//``. 74 | - **title** (string) = The name of the website to display. 75 | 76 | Jekyll 77 | ------ 78 | 79 | Installation 80 | ~~~~~~~~~~~~ 81 | 82 | - Install the dependencies: 83 | 84 | - Arch Linux: 85 | 86 | .. code-block:: sh 87 | 88 | $ sudo pacman -Syy 89 | $ sudo pacman -S ruby base-devel 90 | 91 | - Debian/Ubuntu: 92 | 93 | .. code-block:: sh 94 | 95 | $ sudo apt-get update 96 | $ sudo apt-get install build-essential ruby-full zlib1g-dev 97 | 98 | - Fedora 99 | 100 | .. code-block:: sh 101 | 102 | $ sudo dnf install ruby ruby-devel openssl-devel redhat-rpm-config @development-tools 103 | 104 | - Export the environment variables to use local Ruby Gems. 105 | 106 | .. code-block:: sh 107 | 108 | $ export GEM_HOME="$HOME/gems" 109 | $ export PATH="$HOME/gems/bin:$PATH" 110 | 111 | - Install Jekyll. 112 | 113 | .. code-block:: sh 114 | 115 | $ gem install jekyll bundler 116 | 117 | [2] 118 | 119 | - Create a new blog. 120 | 121 | .. code-block:: sh 122 | 123 | $ jekyll new 124 | 125 | - Start the blog in live reload mode to allow changes to automatically show up. 126 | 127 | .. code-block:: sh 128 | 129 | $ cd 130 | $ bundle exec jekyll serve --livereload 131 | 132 | - Access the webiste locally at ``http://127.0.0.1:35729`` for the live reload session. Otherwise, visit ``http://localhost:4000`` for the normal session. 133 | 134 | [3] 135 | 136 | Themes 137 | ~~~~~~ 138 | 139 | - Find a theme from `here `__. 140 | - Remove the default theme from the ``Gemfile``. The line starts with ``gem "minima"``. 141 | - Add the new theme to the ``Gemfile``. 142 | 143 | :: 144 | 145 | gem "" 146 | 147 | - Install the new theme. 148 | 149 | .. code-block:: sh 150 | 151 | $ bundle install 152 | 153 | - Switch to the new theme in the ``_config.yml`` file. 154 | 155 | :: 156 | 157 | theme: 158 | 159 | [4] 160 | 161 | History 162 | ------- 163 | 164 | - `Latest `__ 165 | 166 | Bibliography 167 | ------------ 168 | 169 | 1. "What Is a CMS and Why Should You Care?" HubSpot Blog. July 29, 2020. Accessed November 24, 2020. https://blog.hubspot.com/blog/tabid/6307/bid/7969/what-is-a-cms-and-why-should-you-care.aspx 170 | 2. "[Jekyll] Installation." Jekyll Documentation. Accessed November 25, 2020. https://jekyllrb.com/docs/installation/ 171 | 3. "[Jekyll] Quickstart." Jekyll Documentation. Accessed November 25, 2020. https://jekyllrb.com/docs/ 172 | 4. "[Jekyll] Themes." Jekyll Documentation. Accessed November 25, 2020. https://jekyllrb.com/docs/themes/ 173 | 5. "Quick Start." Hugo. March 26, 2021. Accessed April 19, 2021. https://gohugo.io/getting-started/quick-start/ 174 | -------------------------------------------------------------------------------- /src/http/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: HTTP 4 | 5 | clustering 6 | cms 7 | databases 8 | http_servers 9 | -------------------------------------------------------------------------------- /src/index.rst: -------------------------------------------------------------------------------- 1 | .. Root Pages documentation master file, created by 2 | sphinx-quickstart on Sat Dec 23 12:50:38 2017. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | Welcome to Root Pages! 7 | ====================== 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | :caption: Administration 12 | 13 | administration/index 14 | 15 | .. toctree:: 16 | :maxdepth: 1 17 | :caption: Automation 18 | 19 | automation/index 20 | 21 | .. toctree:: 22 | :maxdepth: 1 23 | :caption: Computer Hardware 24 | 25 | computer_hardware/index 26 | 27 | .. toctree:: 28 | :maxdepth: 1 29 | :caption: Graphics 30 | 31 | graphics/index 32 | 33 | .. toctree:: 34 | :maxdepth: 1 35 | :caption: HTTP 36 | 37 | http/index 38 | 39 | .. toctree:: 40 | :maxdepth: 1 41 | :caption: Networking 42 | 43 | networking/index 44 | 45 | .. toctree:: 46 | :maxdepth: 1 47 | :caption: Observation 48 | 49 | observation/index 50 | 51 | .. toctree:: 52 | :maxdepth: 1 53 | :caption: OpenStack 54 | 55 | openstack/index 56 | 57 | .. toctree:: 58 | :maxdepth: 1 59 | :caption: Programming 60 | 61 | programming/index 62 | 63 | .. toctree:: 64 | :maxdepth: 1 65 | :caption: Public Clouds 66 | 67 | public_clouds/index 68 | 69 | .. toctree:: 70 | :maxdepth: 1 71 | :caption: Security 72 | 73 | security/index 74 | 75 | .. toctree:: 76 | :maxdepth: 1 77 | :caption: Storage 78 | 79 | storage/index 80 | 81 | .. toctree:: 82 | :maxdepth: 1 83 | :caption: UNIX Distributions 84 | 85 | unix_distributions/index 86 | 87 | .. toctree:: 88 | :maxdepth: 1 89 | :caption: Virtualization 90 | 91 | virtualization/index 92 | 93 | .. toctree:: 94 | :maxdepth: 1 95 | :caption: Windows 96 | 97 | windows/index 98 | 99 | ----- 100 | 101 | .. toctree:: 102 | :maxdepth: 1 103 | :caption: Commands 104 | 105 | commands/index 106 | 107 | 108 | `Contribute to Root Pages! `__ 109 | 110 | -------------------------------------------------------------------------------- /src/networking/firewalls.rst: -------------------------------------------------------------------------------- 1 | Firewalls 2 | ========= 3 | 4 | .. contents:: Table of Contents 5 | 6 | Fail2Ban 7 | -------- 8 | 9 | Fail2Ban uses regular expression to search log files to failed login attempts to various services. Those filters are created for common services such as ``sshd``. They can be configured in "jail" sections that define what additional settings to use with that filter. 10 | 11 | After installation, the main configuration file for enabled filters and bans should be copied to a local file. This file will override the main configuration. Additional configurations can also be stored in ``/etc/fail2ban/jail.d/``. 12 | 13 | .. code-block:: sh 14 | 15 | $ sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local 16 | 17 | Common options: 18 | 19 | - DEFAULT 20 | 21 | - bantime = The amount of time, in seconds, an IP address should be banned. 22 | - findtime = The amount of time, in seconds, for which the maxretry checks for failures. 23 | - ignoreip = This is a list of IP addresses and/or CIDR ranges that are whitelisted. Fail2Ban will not block these addresses. 24 | - maxretry = The number of times a failure is detected before banning the address. 25 | 26 | Each jail section in the configuration file manages a different filter. The values from the ``DEFAULT`` section can be overridden for individual jails. Set ``enabled = true`` in each filter that is desired to be enabled. 27 | 28 | :: 29 | 30 | [sshd] 31 | enabled = true 32 | 33 | Enable and start the service. 34 | 35 | .. code-block:: sh 36 | 37 | $ sudo systemctl enable --now fail2ban 38 | 39 | View Fail2Ban's status and which jail filters are enabled. 40 | 41 | .. code-block:: sh 42 | 43 | $ fail2ban-client status 44 | 45 | Unblock a legitimate IP address: 46 | 47 | .. code-block:: sh 48 | 49 | $ sudo fail2ban-client set sshd unbanip 50 | 51 | [1] 52 | 53 | Uncomplicated Firewall (UFW) 54 | ---------------------------- 55 | 56 | UFW is designed to be easy to use and it is the default firewall for Debian. 57 | 58 | - Quick start. For getting started, it is recommended to set the default rules to allow outgoing traffic and deny incoming traffic. Be sure to keep the SSH port 22 open if necessary. 59 | 60 | .. code-block:: sh 61 | 62 | $ sudo systemctl enable --now ufw 63 | $ sudo ufw default allow outgoing 64 | $ sudo ufw default deny incoming 65 | $ sudo ufw allow 22 66 | $ sudo ufw show added 67 | $ sudo ufw enable 68 | $ sudo ufw status verbose 69 | 70 | - View the status and rules that are enabled. 71 | 72 | .. code-block:: sh 73 | 74 | $ sudo ufw status 75 | $ sudo ufw status numbered 76 | 77 | - View the status including the logging level, default rules, and profiles. 78 | 79 | .. code-block:: sh 80 | 81 | $ sudo ufw status verbose 82 | 83 | - View all of the rules including ones which are not enabled yet. 84 | 85 | .. code-block:: sh 86 | 87 | $ sudo ufw show added 88 | 89 | - Enable the firewall rules. 90 | 91 | .. code-block:: sh 92 | 93 | $ sudo ufw enable 94 | 95 | - If another firewall on the system is enabled, such as Firewalld, UFW will refuse to start on boot and remain in an "inactive" state. Ensure that all other firewalls are disabled. [4] 96 | 97 | .. code-block:: sh 98 | 99 | $ sudo systemctl disable firewalld 100 | 101 | - Disable the firewall rules. 102 | 103 | .. code-block:: sh 104 | 105 | $ sudo ufw disable 106 | 107 | - Configure default rules. 108 | 109 | .. code-block:: sh 110 | 111 | $ sudo ufw default [allow|deny] [incoming|outgoing] 112 | 113 | - Open a port (for both TCP and UDP and both IPv4 and IPv6). 114 | 115 | .. code-block:: sh 116 | 117 | $ sudo ufw allow 118 | 119 | - Open a port using a specific protocol. 120 | 121 | .. code-block:: sh 122 | 123 | $ sudo ufw allow /tcp 124 | $ sudo ufw allow /udp 125 | 126 | - Open a port for IPv4 or IPv6 only. [3] 127 | 128 | .. code-block:: sh 129 | 130 | $ sudo ufw allow proto to 0.0.0.0/0 port 131 | $ sudo ufw allow proto to ::/0 port 132 | 133 | - Open a range of ports. 134 | 135 | .. code-block:: sh 136 | 137 | $ sudo ufw allow : 138 | 139 | - Open a port for a specific IP address or CIDR range. 140 | 141 | .. code-block:: sh 142 | 143 | $ sudo ufw allow from to any port proto 144 | $ sudo ufw allow from / to any port proto 145 | 146 | - Block a port. 147 | 148 | .. code-block:: sh 149 | 150 | $ sudo ufw deny 151 | 152 | - Delete a rule by using the arguments to add the rule. 153 | 154 | - Syntax: 155 | 156 | .. code-block:: sh 157 | 158 | $ sudo ufw delete 159 | 160 | - Example: 161 | 162 | .. code-block:: sh 163 | 164 | $ sudo ufw allow 80 165 | $ sudo ufw delete allow 80 166 | 167 | - Delete a rule by using a number from ``ufw status numbered``. 168 | 169 | .. code-block:: sh 170 | 171 | $ sudo ufw delete 172 | 173 | - Reset the rules. 174 | 175 | .. code-block:: sh 176 | 177 | $ sudo ufw reset 178 | 179 | [2] 180 | 181 | History 182 | ------- 183 | 184 | - `Latest `__ 185 | 186 | Bibliography 187 | ------------ 188 | 189 | 1. "How to install Fail2Ban on CentOS 7." HowtoForge. Accessed June 10, 2018. https://www.howtoforge.com/tutorial/how-to-install-fail2ban-on-centos/ 190 | 2. "Uncomplicated Firewall (ufw)." Debian Wiki. October 15, 2021. Accessed October 19, 2021. 191 | 3. "How do I use ufw to open ports on ipv4 only?" Server Fault. September 24, 2020. Accessed October 19, 2021. https://serverfault.com/questions/809643/how-do-i-use-ufw-to-open-ports-on-ipv4-only 192 | 4. "How can I enable ufw automatically on boot?" Stack Exchange Network - Unix & Linux. September 12, 2021. Accessed October 20, 2021. https://unix.stackexchange.com/questions/182959/how-can-i-enable-ufw-automatically-on-boot 193 | -------------------------------------------------------------------------------- /src/networking/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Networking 4 | 5 | dns_servers 6 | firewalls 7 | linux 8 | -------------------------------------------------------------------------------- /src/observation/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Administration 4 | 5 | logging 6 | monitoring 7 | -------------------------------------------------------------------------------- /src/observation/logging.rst: -------------------------------------------------------------------------------- 1 | Logging 2 | ======= 3 | 4 | .. contents:: Table of Contents 5 | 6 | Overview 7 | -------- 8 | 9 | Logging is the process of collecting metrics from a server and logging them. For managing a large number of server deployments, these logs should be sent to a database server. The database can be queried by a monitoring program to help track down issues and optionally visualize the data. 10 | 11 | :: 12 | 13 | [Log collector] --> [Database] --> [Monitoring dashboard with API and/or UI] 14 | 15 | Collectors: 16 | 17 | - `Apache Flume `__ 18 | - `collectd `__ 19 | - `fluentd `__ 20 | - `Logstash `__ 21 | - `Telegraf `__ 22 | 23 | collectd 24 | -------- 25 | 26 | collectd gathers and distributes metrics of a running system. A full list of metric collection plugins that collectd supports can be found `here `__. [1] 27 | 28 | collectd is available in most major repositories. [2] 29 | 30 | CentOS and RHEL: 31 | 32 | .. code-block:: sh 33 | 34 | $ sudo yum install epel-release 35 | $ sudo yum install collectd 36 | 37 | Debian and Ubuntu: 38 | 39 | .. code-block:: sh 40 | 41 | $ sudo apt-get install collectd 42 | 43 | By default, collectd gathers information about the CPU utilization (``cpu``) and ``load``, network ``interface`` bandwidth, and ``memory`` usage. The hostname and desired plugins should be defined in the ``/etc/collectd.conf`` configuration file at a minimum. 44 | 45 | :: 46 | 47 | Hostname 48 | LoadPlugin 49 | 50 | Define a database server that the network plugin should send the logs to. This can be InfluxDB, Logstash, or any other logging database. Alternatively, the ``dbi`` plugin can be used to connect to many different database back-ends directly. 51 | 52 | :: 53 | 54 | 55 | Server "" "" 56 | 57 | 58 | Start the service. 59 | 60 | .. code-block:: sh 61 | 62 | $ sudo systemctl start collectd 63 | 64 | [3] 65 | 66 | History 67 | ------- 68 | 69 | - `Latest `__ 70 | 71 | Bibliography 72 | ------------ 73 | 74 | 1. "collectd – The system statistics collection daemon." collectd.org. Accessed July 9, 2020. https://collectd.org/ 75 | 2. "[collectd] Download." collectd.org. Accessed July 9, 2020. https://collectd.org/download.shtml 76 | 3. "Monitoring Linux performance with Grafana." August 28, 2017. Accessed July 9, 2020. https://opensource.com/article/17/8/linux-grafana 77 | -------------------------------------------------------------------------------- /src/observation/monitoring.rst: -------------------------------------------------------------------------------- 1 | Monitoring 2 | ========== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Monit 7 | ----- 8 | 9 | Monit is a complete service monitoring software. It has a web interface 10 | that is available by default on the localhost interface via port 2812. 11 | It can detect if a service is down and restart it. Automatic alerts 12 | can also be configured. 13 | 14 | Configuration 15 | ~~~~~~~~~~~~~ 16 | 17 | Install monit: 18 | 19 | RHEL 20 | 21 | .. code-block:: sh 22 | 23 | $ sudo yum install epel-release 24 | $ sudo yum install monit 25 | 26 | Ubuntu 27 | 28 | .. code-block:: sh 29 | 30 | $ sudo apt-get install monit 31 | 32 | Depending on your system, the main configuration file is one of these 33 | two below. The default settings can be used. The configurations are not 34 | case sensitive. 35 | 36 | - /etc/monitrc 37 | - /etc/monit.conf 38 | 39 | The include directory for other configuration files will be on of these 40 | two: 41 | 42 | - /etc/monit.d/ 43 | - /etc/monit/conf.d/ 44 | 45 | [1] 46 | 47 | Global configuration options: 48 | 49 | - SET DAEMON ```` 50 | 51 | - Specify the cycle time in seconds. After this many seconds, each service in the configuration will be polled. 52 | 53 | - SET ALERT ``@
`` 54 | 55 | - Send all alerts to this e-mail address. 56 | 57 | - SET MAILSERVER ```` [````] [USERNAME ````] [PASSWORD ````] 58 | 59 | - Define the mail server to use. This is typically localhost. 60 | 61 | An example of a basic Nginx template is provided below. If the PID is 62 | not found, then monit will continue to attempt to start it until the new 63 | process is spawned. 64 | 65 | Example: 66 | 67 | :: 68 | 69 | check process nginx with pidfile /var/run/nginx.pid 70 | start program = "/bin/systemctl start nginx" 71 | stop program = "/bin/systemctl stop nginx" 72 | 73 | - check system ```` 74 | - Check system resources. 75 | - Checks: 76 | 77 | - IF ```` ```` THEN ```` 78 | 79 | - check process ```` with pidfile ```` 80 | - Verify that the PID is running. 81 | - Checks: 82 | 83 | - IF CHANGED PID THEN ```` 84 | - IF UPTIME ```` value ```` THEN ```` 85 | - IF ```` ```` THEN ```` 86 | 87 | - check file ```` with path ```` 88 | - Verify a file exists with specific attributes. The "check directory" 89 | should be used instead if verifying a directory state. 90 | - Checks: 91 | 92 | - IF FAILED UID ```` THEN ```` 93 | - IF FAILED GID ```` THEN ```` 94 | - IF FAILED PERMISSION ```` THEN ```` 95 | - IF SIZE ```` ```` ```` THEN 96 | ```` 97 | - IF CHANGED SIZE THEN ```` 98 | - IF CHANGED [MD5\|SHA1] CHECKSUM THEN ```` 99 | - IF FAILED [MD5\|SHA1] CHECKSUM [EXPECT ````] THEN 100 | ```` 101 | - IF TIMESTAMP ```` ```` ```` THEN 102 | ```` 103 | 104 | - check program ```` with ```` 105 | - Execute a script and verify it's exit code. 106 | - Checks: 107 | 108 | - IF STATUS ```` ```` THEN ```` 109 | 110 | - check host ```` WITH ADDRESS ```` 111 | - Verify that the remote host is accessible. 112 | - Checks: 113 | 114 | - IF FAILED PING[4\|6] [COUNT ````] [SIZE 115 | ````] [TIMEOUT ```` ````] 116 | [ADDRESS ````] THEN ```` 117 | - IF FAILED PORT ```` [TYPE ``[TCP|UDP]``] [PROTOCOL 118 | ````] 119 | 120 | - check network ```` WITH INTERFACE ```` 121 | - Verify that an IP address exists on the local machine. This is useful 122 | for failover type load balancers. 123 | - Checks: 124 | 125 | - IF FAILED LINK THEN ```` 126 | - IF SATURATION ```` ```` THEN ```` 127 | 128 | - check filesystem ````\ with path 129 | ```` 130 | - Verify statistics about a file system. 131 | 132 | - ```` can be a block device, mount, or directory. 133 | 134 | - Checks: 135 | 136 | - IF SPACE USAGE ```` ```` ```` 137 | THEN ```` 138 | - IF SPACE FREE ```` ```` ```` THEN 139 | ```` 140 | - IF INODE USAGE ```` ```` ```` 141 | THEN ```` 142 | - IF INODE FREE ```` ```` ```` THEN 143 | ```` 144 | 145 | Valid operators: 146 | 147 | - "<", "lt", or "less" 148 | - ">", "gt", or "greater" 149 | - "==", "eq", or "equal" 150 | - "!=", "ne", or "notequal" 151 | 152 | Valid size units: 153 | 154 | - "B", or "byte" 155 | - "KB", or "kilobyte" 156 | - "MB", or "megabyte" 157 | - "GB", or "gigabyte" 158 | - "%", or "percent". 159 | 160 | Valid time units: 161 | 162 | - "SECOND", or "SECONDS" 163 | - "MINUTE", or "MINUTES" 164 | - "HOUR", or "HOURS" 165 | - "DAY", or "DAYS" 166 | 167 | Valid resources: 168 | 169 | - CPU([user\|system\|wait]) 170 | - THREADS 171 | - CHILDREN 172 | - TOTAL MEMORY ```` 173 | - The memory usage of the main process and all of the children. 174 | - MEMORY ```` 175 | - The memory usage of just the main process. Alternatively this can 176 | monitor all of the server's memory usage. 177 | - SWAP ```` 178 | - LOADAVG([1min\|5min\|15min]) 179 | 180 | Valid protocols: 181 | 182 | - dns 183 | - http 184 | - https 185 | - mysql 186 | - smtp 187 | 188 | Valid actions: 189 | 190 | - "ALERT" 191 | - Send an e-mail alert. 192 | - "RESTART" 193 | - Run the restart function (or the stop and then start functions if the 194 | restart command is not specified). This will also send an e-mail 195 | alert. 196 | - "START" 197 | - Run the start service function. 198 | - "STOP" 199 | - Run the stop service function. 200 | - "EXEC" 201 | - Execute a specified script. 202 | - "UNMONITOR" 203 | - Stop monitoring the service. 204 | 205 | [2] 206 | 207 | Event Types: 208 | 209 | - 1=checksum 210 | - 2=resource 211 | - 4=timeout 212 | - 8=timestamp 213 | - 16=size 214 | - 32=connection 215 | - 64=permission 216 | - 128=UID 217 | - 256=GID 218 | - 512=nonexist 219 | - 1024=invalid 220 | - 2048=data 221 | - 4096=exec 222 | - 8192=fsflags 223 | - 16384=icmp 224 | - 32768=content 225 | - 65536=instance 226 | - 131072=action 227 | - 262144=PID 228 | - 524288=PPID 229 | - 1048576=heartbeat 230 | - 2097152=status 231 | - 4194304=uptime [3] 232 | 233 | History 234 | ------- 235 | 236 | - `Latest `__ 237 | - `< 2020.10.01 `__ 238 | - `< 2019.01.01 `__ 239 | - `< 2018.01.01 `__ 240 | 241 | Bibliography 242 | ------------ 243 | 244 | 1. "Installing Monit for Server Monitoring." Linode. October 15, 2015. 245 | Accessed November 22, 2016. 246 | https://www.linode.com/docs/uptime/monitoring/monitoring-servers-with-monit 247 | 2. "Mont Documentation." Accessed September 30, 2016. 248 | https://mmonit.com/monit/documentation/monit.html 249 | 3. "Monit Events." Accessed September 30, 2016. 250 | https://mmonit.com/documentation/http-api/Methods/Events 251 | -------------------------------------------------------------------------------- /src/openstack/contributor.rst: -------------------------------------------------------------------------------- 1 | OpenStack Contributor 2 | ===================== 3 | 4 | .. contents:: Table of Contents 5 | 6 | New Contributor 7 | --------------- 8 | 9 | These are the steps required to sign up as a new OpenStack developer: 10 | 11 | - Sign up for an `Ubuntu One account `__. 12 | - Log into the `OpenDev Gerrit portal `__. 13 | - Agree to the `Individual Contributor License Agreement `__ (ICLA). 14 | - Add a `public SSH key to Gerrit `__. 15 | 16 | [1] 17 | 18 | IRC 19 | --- 20 | 21 | IRC is one of the few ways that OpenStack developers communicate with each other. The connection details to the Freenode service used by OpenStack are listed below. 22 | 23 | - Username: ```` 24 | - Host: irc.freenode.net 25 | - SSL: Yes 26 | - Port: 6697 27 | 28 | Once logged in for the first time, connect to an OpenStack channel such as ``#openstack`` to register an IRC account. [2] 29 | 30 | :: 31 | 32 | /msg nickserv register 33 | 34 | Useful links: 35 | 36 | - `IRC Channels `__. Most channels are named ``#openstack-``. 37 | - `IRC Logs `__ 38 | - `Scheduled project meeting times and channels. `__ 39 | 40 | Git 41 | --- 42 | 43 | Gerrit 44 | ~~~~~~ 45 | 46 | - Install the ``git-review`` via a system package or ``pip``. 47 | - Clone an `OpenStack repository from OpenDev `__ with ``git clone https://opendev.org/openstack/``. 48 | - Add the registered Gerrit username with ``git config --global gitreview.username `` 49 | - Use ``git review -s`` to configure Gerrit for the repository and to ensure the local workstation can connect to it. 50 | - All reviews are posted on `review.opendev.org `__. 51 | - Re-run all CI tests if there is a failure by posting a comment on the review with the word ``recheck`` in it. 52 | 53 | - For the RDO/TripleO community, RDO specific CI jobs can be re-ran by commenting with ``check-rdo``. 54 | 55 | - For a patch to merge, it needs at least ``+2`` from Code-Reviews, a Verified label from CI, and a ``+1`` to Workflow from a core contributor. 56 | - Once a patch is merged into master, consider backporting it to previous stable branches with ``git cherry-pick -x``. 57 | 58 | - It is preferred to backport sequentially from one release to the next (instead of directly from master) to help avoid merge conflicts. 59 | 60 | Gerrit patches can be downloaded and applied to a local environment. Find the patch to download by going to: ``Download`` > ``Patch-File`` > Copy and use the link to the base64 file. 61 | 62 | .. code-block:: sh 63 | 64 | $ cd /usr/lib/python3.6/site-packages 65 | $ sudo patch -p1 < <(base64 --decode <(curl -s "https://review.opendev.org/changes//revisions//patch?download")) 66 | 67 | Git Messages 68 | ~~~~~~~~~~~~ 69 | 70 | When submitting a patch, the git commit message (from ``git commit -m``) can contain any of these valid tags: 71 | 72 | - DNM = Do not merge. This is normally used to manually run CI jobs. 73 | - WIP = Work-in-progress. This patch is not complete and possibly not working yet. It is not ready for reviews yet. 74 | - [Queens-only] 75 | - Closes-Bug: ``#`` 76 | - Resolves: ``rhbz#`` 77 | 78 | - List a Red Hat Bugzilla that the patch resolves. 79 | 80 | - Partial-Bug: 81 | - Related-Bug: 82 | - Task: 83 | - Story: 84 | - Implements: blueprint ```` 85 | - Co-Authored-By: ```` ```` 86 | - Change-Id: ```` 87 | - Depends-On: ```` 88 | - Conflicts: 89 | 90 | - Specify the path to each file that had a merge conflict that was manually resolved. 91 | 92 | :: 93 | 94 | Conflicts: 95 | path/to/conflicting/file.py 96 | path/to/conflicting/file2.py 97 | 98 | Release Notes 99 | ~~~~~~~~~~~~~ 100 | 101 | Any major change to an OpenStack project requires a release note. The categories which can be specified in a release note are: 102 | 103 | - critical 104 | - deprecations 105 | - features 106 | - fixes 107 | - issues 108 | - other 109 | - prelude 110 | - security 111 | - upgrade 112 | 113 | Install the required `reno `__ Python library. 114 | 115 | .. code-block:: sh 116 | 117 | $ pip install --user reno 118 | 119 | Create a new release note using a prefix. The prefix should be either the subject of the change or the Launchpad bug number in the format of ``bug-``. 120 | 121 | .. code-block:: sh 122 | 123 | $ reno new 124 | Created new notes file in releasenotes/notes/-.yaml 125 | 126 | Edit the release note with contents about the major change. 127 | 128 | .. code-block:: sh 129 | 130 | $ vim releasenotes/notes/-.yaml 131 | 132 | [6] 133 | 134 | Bugs 135 | ---- 136 | 137 | The bug tracker system used is Canonical's Launchpad. Generic OpenStack issues can be reported to ``https://bugs.launchpad.net/openstack``. Project specific issues can be found at ``https://bugs.launchpad.net/``. 138 | 139 | Each bug has specific attributes: 140 | 141 | - Affects = The OpenStack project that is affected. 142 | - Status = The current status of the bug. 143 | 144 | - Confirmed 145 | - Fix Committed 146 | - Fix Released 147 | - In Progress 148 | - Incomplete 149 | - Invalid 150 | - New 151 | - Opinion 152 | - Triaged 153 | - Won't Fix 154 | 155 | - Importance = The importance/priority of the bug. 156 | 157 | - Critical 158 | - High 159 | - Medium 160 | - Low 161 | - Wishlist 162 | 163 | - Assigned to = The owner of the bug. 164 | - Milestone = The next development release that this is targeted to be fixed in. 165 | 166 | [3] 167 | 168 | Resources 169 | --------- 170 | 171 | These are various services that are helpful for collaboration and sharing. 172 | 173 | - `Story Board `__ = Project planning. 174 | - `Paste `__ = Paste large code blocks. `Back-end documentation `__. 175 | - `Etherpad `__ = Collaborative online document. `Back-end documentation `__. 176 | - `OpenDev Git Repositories `__ = All of the OpenStack services source code. 177 | 178 | Specification and Blueprint 179 | --------------------------- 180 | 181 | A specification (spec) and blueprint are required for any new large feature or code refactoring. The specification is a detailed document explaining the work that needs to be done and the impact it will have on the project. [4] Some considerations are impacts to the API, security, notifications, end user, performance, etc. A full example of a spec can be found `here `__. Blueprints are created as a more generalized version of a specification. The progress of the new feature is tracked by mentioning the blueprint in related git commit messages. 182 | 183 | Licenses 184 | -------- 185 | 186 | OpenStack is a collection of various different projects that use software licenses that are approved by the Open Source Initiative (OSI). It is recommended that new projects use the Apache Software License v2.0 (ASL v2.0). For supporting the Contributor License Agreement (CLA), a license such as ASL v2.0, BSD, or MIT must be used. [5] 187 | 188 | History 189 | ------- 190 | 191 | - `Latest `__ 192 | 193 | Bibliography 194 | ------------ 195 | 196 | 1. "Developer’s Guide." infra-manual (OpenStack Documentation). August 2, 2019. Accessed December 4, 2019. https://docs.openstack.org/infra/manual/developers.html 197 | 2. "Setup IRC." OpenStack Documentation Contributor Guide. December 19, 2019. Accessed January 2, 2020. https://docs.openstack.org/contributors/common/irc.html 198 | 3. "Bugs." OpenStack Documentation Project Team Guide. June 28, 2018. Accessed January 2, 2020. https://docs.openstack.org/project-team-guide/bugs.html 199 | 4. "Blueprints and specifications." OpenStack Documentation Contributor Guide. January 2, 2020. Accessed January 2, 2020. https://docs.openstack.org/doc-contrib-guide/blueprints-and-specs.html 200 | 5. "Licensing requirements." OpenStack Governance. July 18, 2017. Accessed January 2, 2020. https://governance.openstack.org/tc/reference/licensing.html 201 | 6. "Working with Release Notes." keystone OpenStack Documentation. May 31, 2019. Accessed May 29, 2020. https://docs.openstack.org/keystone/train/contributor/release-notes.html 202 | -------------------------------------------------------------------------------- /src/openstack/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: OpenStack 4 | 5 | openstack 6 | contributor 7 | kolla 8 | openstack-ansible 9 | tripleo 10 | -------------------------------------------------------------------------------- /src/openstack/kolla.rst: -------------------------------------------------------------------------------- 1 | Kolla 2 | ====== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Overview 7 | -------- 8 | 9 | Kolla contains three projects [1]: 10 | 11 | - Kolla = Tools for building OpenStack service containers. 12 | - Kolla Ansible = Deployment tool for Kolla containers. 13 | - Kayobe = Baremetal node provisioning using Kolla, Kolla Ansible, and Bifrost. 14 | 15 | Releases 16 | -------- 17 | 18 | .. csv-table:: 19 | :header: Kolla-Ansible, OpenStack 20 | :widths: 20, 20 21 | 22 | 1, Liberty 23 | 2, Mitaka 24 | 3, Newton 25 | 4, Ocata 26 | 5, Pike 27 | 6, Queens 28 | 7, Rocky 29 | 8, Stein 30 | 9, Train 31 | 10, Ussuri 32 | 33 | [2] 34 | 35 | Kolla-Ansible 36 | ------------- 37 | 38 | Operating systems: 39 | 40 | - Supported: CentOS/RHEL, Debian, Ubuntu 41 | - Recommended: CentOS/RHEL 8 or Ubuntu 18.04 42 | 43 | Kolla-Ansible supports managing different types of nodes. Each node is a defined as a group in Ansible. 44 | 45 | Node types [3]: 46 | 47 | - Control = OpenStack APIs 48 | - Network = Neutron agents 49 | - Compute = Hypervisors 50 | - Storage = Cinder or Swift 51 | - Monitoring = Monitoring services 52 | 53 | Deployment (Quick) 54 | ~~~~~~~~~~~~~~~~~~ 55 | 56 | Requirements: 1 vCPU, 8GB RAM, 40GB storage space, and 2 network interfaces 57 | 58 | This covers how to install an all-in-one OpenStack installation using the Train release of Kolla-Ansible and CentOS 8. 59 | 60 | Install dependencies for Kolla-Ansible: 61 | 62 | .. code-block:: sh 63 | 64 | $ sudo yum install gcc libffi-devel openssl-devel python3-devel python3-libselinux python3-virtualenv 65 | 66 | Create and activate a Python virtual environment. This is to isolate the dependencies and avoid breaking Python packages installed by RPMs. 67 | 68 | .. code-block:: sh 69 | 70 | $ virtualenv ~/kolla-ansible 71 | $ source ~/kolla-ansible/bin/activate 72 | 73 | Install Kolla-Ansible: 74 | 75 | .. code-block:: sh 76 | 77 | $ pip install -U pip setuptools 78 | $ pip install 'ansible<2.10' 79 | $ pip install 'kolla-ansible<10' 80 | 81 | Kolla-Ansible does not support SELinux. However, if SELinux is in permissive mode then Ansible will complain if the ``selinux`` Python library is not installed. [4] 82 | 83 | .. code-block:: sh 84 | 85 | $ pip install selinux 86 | 87 | Copy over the configuration files and sample inventory: 88 | 89 | .. code-block:: sh 90 | 91 | $ sudo mkdir -p /etc/kolla 92 | $ sudo chown $USER:$USER /etc/kolla 93 | $ cp -r ~/kolla-ansible/share/kolla-ansible/etc_examples/kolla/* /etc/kolla 94 | $ cp ~/kolla-ansible/share/kolla-ansible/ansible/inventory/* . 95 | 96 | Generate passwords. These will be stored in ``/etc/kolla/passwords.yml``. 97 | 98 | .. code-block:: sh 99 | 100 | $ kolla-genpwd 101 | 102 | Modify the main configuration file ``/etc/kolla/globals.yml``. 103 | 104 | :: 105 | 106 | kolla_base_distro: "centos" 107 | kolla_install_type: "source" 108 | network_interface: "eth0" 109 | # This interface has to be different than 'network_interface'. 110 | neutron_external_interface: "eth1" 111 | # This IP address will be used to access the OpenStack services. 112 | # It should be an unallocated IP address. 113 | kolla_internal_vip_address: "" 114 | 115 | Configure the inventory to use the Python binary in the virtual environment. This is required to import and use the ``docker`` Python library since there is no packaged RPM for it on EL8. 116 | 117 | .. code-block:: sh 118 | 119 | $ vim all-in-one 120 | 121 | :: 122 | 123 | [control] 124 | localhost ansible_connection=local ansible_python_interpreter=/root/kolla-ansible/bin/python3 125 | 126 | [network] 127 | localhost ansible_connection=local ansible_python_interpreter=/root/kolla-ansible/bin/python3 128 | 129 | [compute] 130 | localhost ansible_connection=local ansible_python_interpreter=/root/kolla-ansible/bin/python3 131 | 132 | [storage] 133 | localhost ansible_connection=local ansible_python_interpreter=/root/kolla-ansible/bin/python3 134 | 135 | [monitoring] 136 | localhost ansible_connection=local ansible_python_interpreter=/root/kolla-ansible/bin/python3 137 | 138 | [deployment] 139 | localhost ansible_connection=local ansible_python_interpreter=/root/kolla-ansible/bin/python3 140 | 141 | Deploy OpenStack: 142 | 143 | .. code-block:: sh 144 | 145 | $ kolla-ansible -i ./all-in-one bootstrap-servers 146 | $ kolla-ansible -i ./all-in-one prechecks 147 | $ kolla-ansible -i ./all-in-one deploy 148 | 149 | Configure the OpenStack utilities: 150 | 151 | .. code-block:: sh 152 | 153 | $ pip install 'python-openstackclient<6.0' 154 | $ kolla-ansible post-deploy 155 | $ . /etc/kolla/admin-openrc.sh 156 | 157 | Setup sample resources on the OpenStack cloud: 158 | 159 | .. code-block:: sh 160 | 161 | $ ~/kolla-ansible/share/kolla-ansible/init-runonce 162 | 163 | [5] 164 | 165 | Configuration 166 | ~~~~~~~~~~~~~ 167 | 168 | All of the configurations are handled in ``/etc/kolla/globals.yml``. 169 | 170 | - kolla_base_distro = ``centos``, ``debian``, ``rhel``, or ``ubuntu``. 171 | - kolla_install_type = ``binary`` (from package manager repository) or ``source`` (from git repository). Using ``source`` is recommended as it gets bug fixes and updates faster. 172 | - network_interface = The interface to use for the API and management networks. 173 | - neutron_external_interface = The interface to use for the Neutron external networks. It cannot be the same as ``network_interface``. 174 | - kolla_internal_vip_address = The private IP address to use for API and management traffic. 175 | - kolla_external_vip_address = The public IP address to use for API and management traffic. 176 | - enable_ = Enable additional services. View the available settings: ``grep ^\#enable_ /etc/kolla/globals.yml``. 177 | - enable_openstack_core = Enable Keystone, Glance, Heat, Horizon, Neutron, and Nova. 178 | 179 | [6] 180 | 181 | History 182 | ------- 183 | 184 | - `Latest `__ 185 | 186 | Bibliography 187 | ------------ 188 | 189 | 1. "Kolla." OpenStack Wiki. Accessed May 29, 2020. https://wiki.openstack.org/wiki/Kolla 190 | 2. "openstack/kolla." opendev. May 28, 2020. Accessed May 29, 2020. https://opendev.org/openstack/kolla 191 | 3. "Production architecture guide." kolla-ansible OpenStack Documentation. January 27, 2020. Accessed May 29, 2020. https://docs.openstack.org/kolla-ansible/latest/admin/production-architecture-guide.html 192 | 4. "Kolla Security." kolla-ansible OpenStack Documentation. April 6, 2018. Accessed May 29, 2020. https://docs.openstack.org/kolla-ansible/train/user/security.html 193 | 5. "Quick Start." kolla-ansible OpenStack Documentation. May 24, 2020. Accessed May 29, 2020. https://docs.openstack.org/kolla-ansible/train/user/quickstart.html 194 | 6. "Kolla Ansible Configuration." kolla-ansible OpenStack Documentation. December 13, 2020. Accessed May 29, 2020. https://docs.openstack.org/kayobe/train/configuration/kolla-ansible.html 195 | -------------------------------------------------------------------------------- /src/programming/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Programming 4 | 5 | c_and_c++ 6 | devops 7 | go 8 | machine_learning 9 | packaging 10 | python 11 | rust 12 | shell 13 | -------------------------------------------------------------------------------- /src/programming/shell.rst: -------------------------------------------------------------------------------- 1 | Shell 2 | ====== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Environment Variables 7 | --------------------- 8 | 9 | Environment variables are commonly used to configure settings for programs. 10 | 11 | - View the current environment variables. 12 | 13 | .. code-block:: sh 14 | 15 | $ env 16 | 17 | - View the value of a specific environment variable. 18 | 19 | .. code-block:: sh 20 | 21 | $ echo $ 22 | 23 | - Temporarily set an environment variable. 24 | 25 | .. code-block:: sh 26 | 27 | $ export = 28 | 29 | - Temporarily delete an environment variable. 30 | 31 | .. code-block:: sh 32 | 33 | $ unset 34 | 35 | - Launch a program using an environment variable. 36 | 37 | .. code-block:: sh 38 | 39 | $ = 40 | 41 | .. code-block:: sh 42 | 43 | $ env = 44 | 45 | - Permanently set an environment variable globally. 46 | 47 | .. code-block:: sh 48 | 49 | $ sudo -E ${EDITOR} /etc/environment 50 | = 51 | 52 | - Permanently set an environment variable for the local user. 53 | 54 | .. code-block:: sh 55 | 56 | $ mkdir -p "${HOME}/.config/environment.d/" 57 | $ ${EDITOR} "${HOME}/.config/environment.d/.conf" 58 | = 59 | 60 | Locale 61 | ------ 62 | 63 | A locale affects the language, calendar, currency, and other values used by the system. 64 | 65 | View all locales. 66 | 67 | .. code-block:: sh 68 | 69 | $ locale --all-locales 70 | 71 | View all top-level keyboard configurations. 72 | 73 | .. code-block:: sh 74 | 75 | $ localectl list-x11-keymap-layouts 76 | 77 | Optionally view keyboard configuration variants. 78 | 79 | .. code-block:: sh 80 | 81 | $ localectl list-x11-keymap-variants 82 | 83 | Example of setting U.S.A. default values. [8][9] 84 | 85 | .. code-block:: sh 86 | 87 | $ localectl set-locale LANG=en_US.utf8 88 | $ localectl set-locale LC_MESSAGES=C 89 | $ localectl set-keymap us 90 | 91 | The keymap can also be set manually. [10] 92 | 93 | .. code-block:: sh 94 | 95 | $ sudo -E ${EDITOR} /etc/vconsole.conf 96 | KEYMAP=us 97 | 98 | ANSI Colors 99 | ----------- 100 | 101 | The color of text and/or the background of text can be modified by using ANSI color codes. Use ``echo`` with escape codes enabled to display various different colors. The ``\033[0m`` escape code will reset the the TTY back to its original color scheme. Otherwise, the color settings will stay. 102 | 103 | .. code-block:: sh 104 | 105 | $ echo -e "\033[32mHello green world\033[0m" 106 | 107 | ANSI only officially supports 8 colors: 108 | 109 | - Black = ``\033[30m`` 110 | - Red = ``\033[31m`` 111 | - Yellow = ``\033[33m`` 112 | - Green = ``\033[32m`` 113 | - Cyan = ``\033[36m`` 114 | - Blue = ``\033[34m`` 115 | - Magenta = ``\033[35m`` 116 | - White = ``\033[37m`` 117 | 118 | It also supports background colors [1]: 119 | 120 | - Black = ``\033[40m`` 121 | - Red = ``\033[41m`` 122 | - Yellow = ``\033[43m`` 123 | - Green = ``\033[42m`` 124 | - Cyan = ``\033[46m`` 125 | - Blue = ``\033[44m`` 126 | - Magenta = ``\033[45m`` 127 | - White = ``\033[47m`` 128 | 129 | Most modern programs support 256 color codes for even more colors and variety. Use ``\033[38;5;<256_COLOR_CODE>m`` to display any of these colors. [2] 130 | 131 | 256 color codes: 132 | 133 | - 0-7 = ANSI. 134 | - 8-15 = High intensity. 135 | - 16-231 = Wide range of colors. 136 | 137 | - 16 = Black. 138 | - 231 = White. 139 | 140 | - 232-255 = Grayscale. 141 | 142 | Reset codes [1][4]: 143 | 144 | - Text only = ``\033[39m`` 145 | - Background only = ``\033[49m`` 146 | - Text and background = ``\033[0m`` 147 | 148 | Understanding ANSI color codes: 149 | 150 | - Example (red background text): ``\033[41m`` 151 | 152 | - ``\033`` (octal) or ``\x1b`` (hexadecimal) is the escape sequence that denotes that this is an ANSI color code. [5] 153 | - ``[`` or ``[0;`` by default means that no special stylization is applied. Alternatives include [3]: 154 | 155 | - ``[1;`` = bold. 156 | - ``[2;`` = low intensity. 157 | - ``[3;`` = italicize. 158 | - ``[4;`` = underline. 159 | - ``[9;`` = high intensity. 160 | 161 | - ``4`` denotes background color. Alternatives include: 162 | 163 | - ``3`` = text color. 164 | - ``10`` = high intensity background color. 165 | 166 | - The last number ``1`` denotes the actual color. 167 | - ``m`` denotes the end of the ANSI color code. 168 | 169 | Zsh 170 | --- 171 | 172 | Differences with Bash 173 | ~~~~~~~~~~~~~~~~~~~~~ 174 | 175 | - Arrays are used differently. 176 | 177 | - Bash: 178 | 179 | .. code-block:: sh 180 | 181 | CMD=(echo Hello world) 182 | ${CMD[*]} 183 | 184 | - Zsh: 185 | 186 | .. code-block:: sh 187 | 188 | CMD=(echo Hello world) 189 | $CMD 190 | 191 | - If nothing is found with a wildcard ``*`` blob, then Zsh will fail and exit the script immediately. This is because Zsh itself tries to expand it instead of sending the wildcard to the application. Use ``setopt`` to make the behavior the same as Bash. [6] 192 | 193 | .. code-block:: sh 194 | 195 | setopt +o nomatch 196 | ls /tmp/foobar* 197 | 198 | - Zsh will always preserve newlines when outputting a variable. However, Bash will only preserve newlines when the variable is quoted. [7] 199 | 200 | .. code-block:: sh 201 | 202 | $ foobar=$(echo -e "foo\nbar") 203 | $ echo ${foobar} 204 | $ echo "${foobar}" 205 | 206 | :: 207 | 208 | foo bar 209 | foo 210 | bar 211 | 212 | History 213 | ------- 214 | 215 | - `Latest `__ 216 | 217 | Bibliography 218 | ------------ 219 | 220 | 1. "How to change the color of your Linux terminal." Opensource.com. September 19, 2019. Accessed July 31, 2023. https://opensource.com/article/19/9/linux-terminal-colors 221 | 2. "Add Color with ANSI in JavaScript." CodeHS. Accessed June 30, 2024. https://codehs.com/tutorial/ryan/add-color-with-ansi-in-javascript 222 | 3. "The entire table of ANSI color codes working in C!" GitHub RabaDabaDoba/ANSI-color-codes.h. July 10, 2023. Accessed July 31, 2023. https://gist.github.com/RabaDabaDoba/145049536f815903c79944599c6f952a 223 | 4. "How to stop the effect of ANSI text color code or set text color back to default after certain characters?" Stack Overflow. April 21, 2023. Accessed July 31, 2023. https://stackoverflow.com/questions/43539956/how-to-stop-the-effect-of-ansi-text-color-code-or-set-text-color-back-to-default 224 | 5. "How do I print colored text to the terminal in Rust?" Stack Overflow. January 24, 2023. Accessed July 31, 2023. https://stackoverflow.com/questions/69981449/how-do-i-print-colored-text-to-the-terminal-in-rust 225 | 6. "Why zsh tries to expand * and bash does not?" Stack Overflow. May 7, 2022. Accessed February 20, 2024. https://stackoverflow.com/questions/20037364/why-zsh-tries-to-expand-and-bash-does-not 226 | 7. "How to preserve line breaks when storing command output to a variable? [duplicate]." Stack Overflow. August 9, 2023. Accessed February 20, 2024. https://stackoverflow.com/questions/22101778/how-to-preserve-line-breaks-when-storing-command-output-to-a-variable 227 | 8. "System Locale and Keyboard Configuration." Fedora User Docs. December 9, 2024. Accessed December 10, 2024. https://docs.fedoraproject.org/en-US/fedora/f40/system-administrators-guide/basic-system-configuration/System_Locale_and_Keyboard_Configuration/ 228 | 9. "Locale." ArchWiki. December 1, 2024. Accessed December 10, 2024. https://wiki.archlinux.org/title/Locale 229 | 10. "Setting Keyboard Layout." Fedora CoreOS. February 7, 2024. Accessed December 10, 2024. https://docs.fedoraproject.org/en-US/fedora-coreos/sysconfig-setting-keymap/ 230 | -------------------------------------------------------------------------------- /src/public_clouds/amazon_web_services.rst: -------------------------------------------------------------------------------- 1 | Amazon Web Services (AWS) 2 | ========================= 3 | 4 | .. contents:: Table of Contents 5 | 6 | AWS CLI 7 | ------- 8 | 9 | **Installation:** 10 | 11 | - Arch Linux: 12 | 13 | .. code-block:: sh 14 | 15 | $ sudo pacman -S aws-cli 16 | 17 | - Debian: 18 | 19 | .. code-block:: sh 20 | 21 | $ sudo apt-get install awscli 22 | 23 | - Fedora 24 | 25 | .. code-block:: sh 26 | 27 | $ sudo dnf install awscli2 28 | 29 | - Other: 30 | 31 | .. code-block:: sh 32 | 33 | $ wget https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip 34 | $ unzip awscli-exe-linux-x86_64.zip 35 | $ sudo ./aws/install 36 | $ /usr/local/bin/aws version 37 | $ rm -r -f ./aws/ ./awscli-exe-linux-x86_64.zip 38 | 39 | [1][2] 40 | 41 | **Configuration:** 42 | 43 | Before using the AWS CLI, it needs login information for an existing account. [3] 44 | 45 | .. code-block:: sh 46 | 47 | $ aws configure 48 | AWS Access Key ID [None]: 49 | AWS Secret Access Key [None]: 50 | Default region name [None]: 51 | Default output format [None]: None 52 | 53 | History 54 | ------- 55 | 56 | - `Latest `__ 57 | 58 | Bibliography 59 | ------------ 60 | 61 | 1. "Install or update the latest version of the AWS CLI." AWS Documentation. Accessed August 28, 2023. https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html 62 | 2. "How to install aws cli on Linux." nixCraft. January 27, 2023. Accessed August 28, 2023. https://www.cyberciti.biz/faq/how-to-install-aws-cli-on-linux/ 63 | 3. "How to Install and Configure AWS CLI on Linux." DevOpsCube. December 7, 2022. Accessed August 28, 2023. https://devopscube.com/install-configure-aws-cli-linux/ 64 | -------------------------------------------------------------------------------- /src/public_clouds/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Public Clouds 4 | 5 | amazon_web_services 6 | microsoft_azure 7 | -------------------------------------------------------------------------------- /src/security/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Security 4 | 5 | authentication 6 | linux_security 7 | mandatory_access_control 8 | -------------------------------------------------------------------------------- /src/security/mandatory_access_control.rst: -------------------------------------------------------------------------------- 1 | Mandatory Access Control (MAC) 2 | ============================== 3 | 4 | .. contents:: Table of Contents 5 | 6 | AppArmor 7 | -------- 8 | 9 | Install 10 | ~~~~~~~ 11 | 12 | - Install the ``apparmor`` package. 13 | - Add AppArmor to the Linux secuirty modules that will be used on boot along with the dependencies that should be loaded beforehand. This is normally done through GRUB. 14 | 15 | :: 16 | 17 | lsm=landlock,lockdown,yama,apparmor,bpf 18 | 19 | - Enable the service. 20 | 21 | .. code-block:: sh 22 | 23 | $ sudo systemctl enable apparmor 24 | 25 | - Reboot the computer to complete the installation. 26 | - Verify that it is enabled and running. 27 | 28 | .. code-block:: sh 29 | 30 | $ sudo aa-enabled 31 | $ sudo aa-status 32 | 33 | [1] 34 | 35 | Profiles 36 | ~~~~~~~~ 37 | 38 | - View loaded profiles: 39 | 40 | .. code-block:: sh 41 | 42 | $ sudo aa-status 43 | 44 | - List other example profiles (included with the ``apparmor-profiles`` package): 45 | 46 | .. code-block:: sh 47 | 48 | $ ls /usr/share/apparmor/extra-profiles/ 49 | 50 | - Copy an example profile. All profiles that will be enabled have to be in the ``/etc/apparmor.d/`` directory [4]: 51 | 52 | .. code-block:: sh 53 | 54 | $ sudo cp /usr/share/apparmor/extra-profiles/ /etc/apparmor.d/ 55 | 56 | - Check for issues with the profile: 57 | 58 | .. code-block:: sh 59 | 60 | $ sudo apparmor_parser --preprocess /etc/apparmor.d/ 61 | 62 | - Add a new profile: 63 | 64 | .. code-block:: sh 65 | 66 | $ sudo apparmor_parser --replace /etc/apparmor.d/ 67 | 68 | - Find the actual name of a profile (it is not always the file name): 69 | 70 | .. code-block:: sh 71 | 72 | $ grep -P ^profile /etc/apparmor.d/ 73 | 74 | - Enable a profile: 75 | 76 | .. code-block:: sh 77 | 78 | $ sudo aa-enforce 79 | 80 | - Disable a profile but keep logging enabled: 81 | 82 | .. code-block:: sh 83 | 84 | $ sudo aa-complain 85 | 86 | - Disable a profile completely: 87 | 88 | .. code-block:: sh 89 | 90 | $ sudo ln -s /etc/apparmor.d/ /etc/apparmor.d/disable/ 91 | $ sudo apparmor_parser --remove /etc/apparmor.d/ 92 | 93 | [2] 94 | 95 | - Delete a profile [3]: 96 | 97 | .. code-block:: sh 98 | 99 | $ sudo rm -f /etc/apparmor.d/ 100 | $ sudo systemctl reload apparmor 101 | 102 | Disable 103 | ~~~~~~~ 104 | 105 | For testing purposes, AppArmor can be temporarily disabled. Set the Linux kernel boot arguments to disable AppArmor. 106 | 107 | :: 108 | 109 | apparmor=0 110 | 111 | Alternatively, use a different MAC such as SELinux. Only one MAC implementation can be used on Linux at a time. [2] 112 | 113 | :: 114 | 115 | security=selinux 116 | 117 | [2] 118 | 119 | SELinux 120 | ------- 121 | 122 | Logs 123 | ~~~~ 124 | 125 | View temporary logs with ``dmesg`` (lost on reboot) or enable persistent SELinux logs at ``/var/log/audit/audit.log``. [5] 126 | 127 | .. code-block:: sh 128 | 129 | $ sudo dmesg | grep -e type=1300 -e type=1400 130 | 131 | .. code-block:: sh 132 | 133 | $ sudo dnf install audit 134 | $ sudo systemctl start auditd 135 | # Logs from the last 10 minutes. 136 | $ sudo ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts recent 137 | # Logs since midnight. 138 | $ sudo ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts today 139 | # All logs that are also human-readable logs 140 | $ sudo audit2allow -w -a 141 | 142 | Additionally check journald logs which will contain different log entries. 143 | 144 | .. code-block:: sh 145 | 146 | $ sudo journalctl -t setroubleshoot 147 | 148 | Some verbose logs are disabled by default. Disable ``dontaudit`` rules, view the logs, then re-enable it. 149 | 150 | .. code-block:: sh 151 | 152 | $ sudo semodule -B -D 153 | 154 | .. code-block:: sh 155 | 156 | $ sudo semodule -B 157 | 158 | View more details about a specific violation. [6] 159 | 160 | .. code-block:: sh 161 | 162 | $ sudo sealert -l 163 | 164 | Profiles 165 | ~~~~~~~~ 166 | 167 | Automatically create, view, and install a profile based on violations in ``/var/log/audi/audit.log``. [5] 168 | 169 | .. code-block:: sh 170 | 171 | $ sudo audit2allow -a -M 172 | $ cat .pp 173 | $ sudo semodule -i .pp 174 | 175 | Disable 176 | ~~~~~~~ 177 | 178 | Temporarily switch between permissive and enforcing mode. 179 | 180 | .. code-block:: sh 181 | 182 | $ getenforce 183 | Permissive 184 | $ sudo setenforce 1 185 | $ getenforce 186 | Enforcing 187 | 188 | .. code-block:: sh 189 | 190 | $ getenforce 191 | Enforcing 192 | $ sudo setenforce 0 193 | $ getenforce 194 | Permissive 195 | 196 | Permanently switch between permissive, enforcing, or disabled modes. A reboot is required. 197 | 198 | .. code-block:: sh 199 | 200 | $ sudo vim /etc/selinux/config 201 | SELINUX=permissive 202 | 203 | .. code-block:: sh 204 | 205 | $ sudo vim /etc/selinux/config 206 | SELINUX=enforcing 207 | 208 | .. code-block:: sh 209 | 210 | $ sudo vim /etc/selinux/config 211 | SELINUX=disabled 212 | 213 | If SELinux was fully disabled with ``SELINUX=disabled`` and has been enabled again, then all files need to be relabeled to prevent issues on the next boot. [5][7] 214 | 215 | - If switching from disabled to permissive mode: 216 | 217 | .. code-block:: sh 218 | 219 | $ sudo touch /.autorelabel 220 | $ sudo reboot 221 | 222 | - If switching from disabled to enforcing mode: 223 | 224 | .. code-block:: sh 225 | 226 | $ sudo fixfiles -F onboot 227 | $ sudo reboot 228 | 229 | - bootc = No changes are needed. bootc will automatically fix label issues. 230 | 231 | Most operating systems use targeted type for SELinux since it is less restrictive. Multi-Level Security (MLS) was created for more strict policies to compile with military standards. 232 | 233 | Change the SELinux type. It is also recommended to first set ``SELINUX=permissive`` before using ``SELINUX=enforcing`` to help troubleshoot any issues. [8] 234 | 235 | .. code-block:: sh 236 | 237 | $ sudo vim /etc/selinux/config 238 | SELINUXTYPE=targeted 239 | 240 | .. code-block:: sh 241 | 242 | $ sudo vim /etc/selinux/config 243 | SELINUXTYPE=mls 244 | 245 | History 246 | ------- 247 | 248 | - `Latest `__ 249 | 250 | Bibliography 251 | ------------ 252 | 253 | 1. "AppArmor." Arch Wiki. September 15, 2021. Accessed October 3, 2021. https://wiki.archlinux.org/title/AppArmor 254 | 2. "AppArmor." Ubuntu Community Help Wiki. July 5, 2020. https://help.ubuntu.com/community/AppArmor 255 | 3. "Building Profiles from the Command Line." openSUSE Security Guide. 2018. Accessed October 3, 2021. https://doc.opensuse.org/documentation/leap/archive/42.3/security/html/book.security/cha.apparmor.commandline.html 256 | 4. "AppArmor HowToUse." Debian Wiki. February 28, 2025. Accessed June 23, 2025. https://wiki.debian.org/AppArmor/HowToUse 257 | 5. "Everything you wanted to know about SELinux but were afraid to run." Open Source Watch. May 14, 2024. Accessed July 3, 2025. https://opensourcewatch.beehiiv.com/p/everything-wanted-know-selinux-afraid-run 258 | 6. "Troubleshooting Problems Related to SELinux." Fedora Quick Docs. June 18, 2023. Accessed July 3, 2025. https://docs.fedoraproject.org/en-US/quick-docs/selinux-troubleshooting/ 259 | 7. "A sysadmin's guide to SELinux: 42 answers to the big questions." Opensource.com July 12, 2018. Accessed July 3, 2025. https://opensource.com/article/18/7/sysadmin-guide-selinux 260 | 8. "Chapter 6. Using Multi-Level Security (MLS)." Red Hat Documentation. Accessed July 3, 2025. https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/10/html/using_selinux/using-multi-level-security-mls 261 | -------------------------------------------------------------------------------- /src/storage/backup_and_recovery.rst: -------------------------------------------------------------------------------- 1 | Backup and Recovery 2 | =================== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Philosophies 7 | ------------ 8 | 9 | 3-2-1 10 | ~~~~~ 11 | 12 | The principles of the 3-2-1 backup philosophy help to effectively backup data. That data can be recovered in a worst-case scenario where one or two backups may be corrupted or lost. 13 | 14 | - 3 = Keep three backups of a file. 15 | - 2 = Keep two backups on different storage devices. 16 | - 1 = Keep one backup in a remote location. 17 | 18 | These are the absolute minimum. More backups can be used as needed. [1] 19 | 20 | Btrfs 21 | ----- 22 | 23 | grub-btrfs 24 | ~~~~~~~~~~ 25 | 26 | The `Antynea/grub-btrfs `__ project will automatically generate GRUB entries for every Btrfs snapshot. 27 | 28 | Install: 29 | 30 | .. code-block:: sh 31 | 32 | $ git clone https://github.com/Antynea/grub-btrfs.git 33 | $ cd grub-btrfs 34 | $ sudo make install 35 | 36 | It can now be configured. Change the GRUB submenu entry name to an agnostic name (by default, it will say "ArchLinux Snapshots"). 37 | 38 | .. code-block:: sh 39 | 40 | $ sudo ${EDITOR} /etc/default/grub-btrfs/config 41 | GRUB_BTRFS_SUBMENUNAME="Btrfs Snapshots" 42 | 43 | Now, whenever the GRUB configuration is re-generated, the Btrfs snapshots will be shown on boot. 44 | 45 | .. code-block:: sh 46 | 47 | $ sudo grub-mkconfig -o /boot/grub/grub.cfg 48 | 49 | dd 50 | -- 51 | 52 | Compressed Backup 53 | ~~~~~~~~~~~~~~~~~ 54 | 55 | It is possible to create a backup of a storage device while compressing the live streamed data. 56 | 57 | - XZ for maximum compression. [8] 58 | 59 | - Create a backup using XZ compression. 60 | 61 | .. code-block:: sh 62 | 63 | $ sudo dd if=/dev/ status=progress | xz --stdout > .img.xz 64 | 65 | - Restore a backup using XZ decompression. 66 | 67 | .. code-block:: sh 68 | 69 | $ xz --decompress --stdout .img.xz | sudo dd of=/dev/ status=progress 70 | 71 | - Zstandard for a balance of compression and speed. [9] 72 | 73 | - Create a backup using Zstandard compression. 74 | 75 | .. code-block:: sh 76 | 77 | $ sudo dd if=/dev/ status=progress | zstd > .img.zst 78 | 79 | - Restore a backup using XZ decompression. 80 | 81 | .. code-block:: sh 82 | 83 | $ zstdcat .img.zst | sudo dd of=/dev/ status=progress 84 | 85 | Clonezilla 86 | ---------- 87 | 88 | Introduction 89 | ~~~~~~~~~~~~ 90 | 91 | `Clonezilla `__ is a live Debian ISO that can do a fast and efficient backup of a drive. It takes into account file systems, sector sizes, and partition alignment. It is recommended to use this over ``dd``. [2][3] However, Clonezilla does not support going from a large drive to a small drive. [7] 92 | 93 | Drive to Drive 94 | ~~~~~~~~~~~~~~ 95 | 96 | Clonezilla can clone from one drive to another. 97 | 98 | - `Download `__ Clonezilla. 99 | - Use ``dd`` on Linux or Rufus on Windows to flash the Clonezilla ISO to an external drive. 100 | - For backing up a Windows >= 8 drive, first fully shutdown the operating system. Fast Startup is enabled by default which makes it so the "Shutdown" button in Windows acts more like a hibernate state. [4] 101 | 102 | :: 103 | 104 | C:\Windows\system32>shutdown /s /f /t 0 105 | 106 | - Boot into Clonezilla. Select all of the default options until you get to the "Select mode:" screen. 107 | - Select the "device-device" mode. 108 | - Select "Beginner mode". 109 | - Select "disk_to_local_disk local_disk_to_local_disk_clone". 110 | - Choose the source/original storage device. 111 | - Choose the destination/new storage device. 112 | - Select "-sfsck" to skip checking the file system. 113 | - Select "-k0 Use the partition table from the source disk". [5] 114 | - Select what to do after the clone is complete: "choose" when done, "true" for getting a command prompt, "reboot", or "shutdown". 115 | 116 | After the drive has been cloned, it is required to resize and/or move the partitions to take advantage of the increased space. [6] 117 | 118 | History 119 | ------- 120 | 121 | - `Latest `__ 122 | 123 | Bibliography 124 | ------------ 125 | 126 | 1. "The 3-2-1 Backup Rule – An Efficient Data Protection Strategy." NAKIVO. November 13, 2017. Accessed September 5, 2020. https://www.nakivo.com/blog/3-2-1-backup-rule-efficient-data-protection-strategy/ 127 | 2. "[SOLVED] dd or clonezilla." Ubuntu Forums. May 3, 2018. Accessed July 30, 2023. https://ubuntuforums.org/showthread.php?t=2390792 128 | 3. "Why is Clonezilla faster than dd?" Server Fault. January 8, 2021. Accessed July 30, 2023. https://serverfault.com/questions/495723/why-is-clonezilla-faster-than-dd 129 | 4. "How to Fully Shutdown Windows?" Vovsoft. July 30, 2023. March 15, 2023. https://vovsoft.com/blog/how-to-fully-shutdown-windows/ 130 | 5. "[Solved] Clonzilla Does Not See New SSD." Linux Mint Forums. June 26, 2021. Accessed July 30, 2023. https://forums.linuxmint.com/viewtopic.php?t=351705 131 | 6. "How to clone a Windows 10 installation to new drive using Clonezilla." Pureinfotech. June 29, 2023. Accessed July 30, 2023. https://pureinfotech.com/clone-windows-10-drive-clonezilla/ 132 | 7. "DRBL/Clonezilla FAQ/Q&A." DRBL. July 1, 2023. Accessed July 30, 2023. https://drbl.org/fine-print.php?path=./faq/2_System/25_restore_larger_disk_to_smaller_one.faq#25_restore_larger_disk_to_smaller_one.faq 133 | 8. "Backup to and Restore from a Disk Image in Linux." COMFILE Technology's Documentation Library. March 6, 2024. Accessed July 19, 2024. http://comfilewiki.co.kr/en/doku.php?id=cupc:backup_restore:index 134 | 9. "compressing and decompressing dd image - zstd instead of gzip." Unix & Linux Stack Exchange. September 10, 2022. Accessed July 19, 2024. https://unix.stackexchange.com/questions/492773/compressing-and-decompressing-dd-image-zstd-instead-of-gzip 135 | -------------------------------------------------------------------------------- /src/storage/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Storage 4 | 5 | backup_and_recovery 6 | bootloaders 7 | ceph 8 | file_systems 9 | -------------------------------------------------------------------------------- /src/template.rst: -------------------------------------------------------------------------------- 1 | Header 1 2 | ======== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Header 2 7 | -------- 8 | 9 | The configuration for this example program has many arguments. [1] 10 | 11 | Syntax: 12 | 13 | .. code-block:: sh 14 | 15 | $ examplecommand 16 | 17 | Common options shown via an unordered list [2]: 18 | 19 | - foo = Print out the word ``foo``. 20 | - bar = This will pour you a drink. 21 | - test = Run a specific test. 22 | 23 | - integer = Print out integers. 24 | - char = Print out characters. 25 | - root = Print out the word ``foo`` only when ran the root user. Example: 26 | 27 | - This is a really realy really really reall really really really really really 28 | really long line for a list item. 29 | 30 | .. code-block:: sh 31 | 32 | $ sudo examplecommand test root 33 | foo 34 | 35 | Ordered list: 36 | 37 | 1. open 38 | 2. source 39 | 3. wins 40 | 41 | Header 3 42 | ~~~~~~~~ 43 | 44 | RST grid table: 45 | 46 | +----------+----------+----------+ 47 | | Column 1 | Column 2 | Column 3 | 48 | +==========+==========+==========+ 49 | | abc | 123 | A3 | 50 | +----------+----------+----------+ 51 | | def | 456 | B3 | 52 | +----------+----------+----------+ 53 | | ghi | 789 | C3 | 54 | +----------+----------+----------+ 55 | 56 | RST comma separated value (CSV) table: 57 | 58 | .. csv-table:: 59 | :header: Name, Description, Enabled 60 | :widths: 20, 20, 20 61 | 62 | Example, "There is a comma , in this sentence.", True 63 | Another Example, 123456, False 64 | Example #3, This is a long setence with no commas., True 65 | Ex, "This has working ""quotes"", Value 66 | 67 | Header 4 68 | ^^^^^^^^ 69 | 70 | Header 5 71 | '''''''' 72 | 73 | Header 6 74 | &&&&&&&& 75 | 76 | Troubleshooting 77 | --------------- 78 | 79 | Tips 80 | ~~~~ 81 | 82 | Error Messages 83 | ~~~~~~~~~~~~~~ 84 | 85 | - ``[WARN] Invalid parameter found.`` = A variable in the configuration is invalid. Review the configuration file for any issues. 86 | 87 | Error Codes 88 | ~~~~~~~~~~~ 89 | 90 | - 0 = Success 91 | - 1 = Failure 92 | 93 | History 94 | ------- 95 | 96 | - `Latest `__ 97 | 98 | Bibliography 99 | ------------ 100 | 101 | 1. "Article title." Example Website Name. January 1, 2018. Accessed January 2, 2018. https://example.tld 102 | 2. "Installation." Another Example Website Name. January 15, 2018. Accessed March 1, 2018. https://another.example.tld 103 | -------------------------------------------------------------------------------- /src/unix_distributions/asahi_linux.rst: -------------------------------------------------------------------------------- 1 | Asahi Linux 2 | =========== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Introduction 7 | ------------ 8 | 9 | Asahi Linux is a build of Arch Linux for Apple Silicon devices. The goal of the project is to reverse-engineer that hardware and work towards upstreaming support for it in all of the various open source projects in the Linux community. 10 | 11 | Installation 12 | ------------ 13 | 14 | Requirements: 15 | 16 | - macOS >= 12.3 17 | - 53 GB of free space 18 | 19 | There is no offline installation media yet. Asahi Linux must be installed using an online connection to download the latest in-development packages. 20 | 21 | The installation will configure a dual-boot. Since Ashai Linux is not stable yet and macOS provides updated firmware files, macOS is left installed. 22 | 23 | Three options are provided for the installation: 24 | 25 | 1. Ashai Linux with the KDE Plasma desktop environment 26 | 2. Ashai Linux without the KDE Plasma desktop environment (terminal only) 27 | 3. UEFI environment for testing other Linux operating systems 28 | 29 | Start the installer: 30 | 31 | .. code-block:: sh 32 | 33 | $ curl https://alx.sh | sh 34 | 35 | [1] 36 | 37 | Uninstallation 38 | -------------- 39 | 40 | **Manual (RECOMMENDED)** 41 | 42 | The manual process for uninstalling Asahi Linux is less likely to corrupt the macOS installation. 43 | 44 | - Find and delete the EFI partition for Asahi Linux. 45 | 46 | .. code-block:: sh 47 | 48 | $ diskutil list | grep ASAHI 49 | $ diskutil eraseVolume JHFS+ drive /dev/ 50 | 51 | - Delete the other Asahi Linux partitions using Disk Utility. This will automatically resize the macOS partition to use all available space again. 52 | 53 | - Disk Utility > Partition > (delete only these 3 partitions: (1) "drive" or "driver" which is 500 MB, (2) Asahi Linux which is 2.5 GB, and (3) the large partition that is NOT "Macintosh HD") > Apply > Partition > Done 54 | 55 | - Reboot macOS. If Asahi Linux was configured to boot by default instead of macOS, the boot process will fail saying "Custom kernel failed to boot." Configure the Mac to use macOS by default [2]: 56 | 57 | - Startup Disk... > Macintosh HD > Restart... 58 | 59 | **Automatic (NOT recommended)** 60 | 61 | The automatic process for uninstalling Asahi Linux is more likely to corrupt the macOS installation. [3] 62 | 63 | .. code-block:: sh 64 | 65 | $ curl -L https://alx.sh/wipe-linux | sudo sh 66 | 67 | Boot 68 | ---- 69 | 70 | On macOS, to get to the boot menu [4]: 71 | 72 | - Hold the power button. It will say "Continue holding for startup options...". 73 | - Release the power button when it says "Loading startup options...". 74 | - Select either "Macintosh HD", "Asahi Linux", or "Fedora Linux". 75 | 76 | Google Chrome 77 | ------------- 78 | 79 | There is no Arm build of Google Chrome for Linux despite there being one for ChromeOS, macOS, and Windows. [5] However, it is possible to install the open source Chromium project and provide an API key to access Google services including account sign-in. [6] 80 | 81 | .. code-block:: sh 82 | 83 | $ flatpak install org.chromium.Chromium 84 | $ flatpak \ 85 | override \ 86 | --user \ 87 | --env=GOOGLE_DEFAULT_CLIENT_ID=77185425430.apps.googleusercontent.com \ 88 | --env=GOOGLE_DEFAULT_CLIENT_SECRET=OTJgUOQcT7lO7GsGZq2G4IlT \ 89 | org.chromium.Chromium 90 | 91 | History 92 | ------- 93 | 94 | - `Latest `__ 95 | 96 | Bibliography 97 | ------------ 98 | 99 | 1. "The first Asahi Linux Alpha Release is here!" Ashai Linux. March 18, 2022. Accessed June 17, 2023. https://asahilinux.org/2022/03/asahi-linux-alpha-release/ 100 | 2. "How to Uninstall Asahi Linux on M1 Mac - Remove all Partitions & Volumes." YouTube Mr. Macintosh. March 24, 2022. Accessed August 2, 2023. https://www.youtube.com/watch?v=nMnWTq2H-N0 101 | 3. "How to uninstall?" Reddit r/AsahiLinux. July 23, 2023. Accessed August 2, 2023. https://www.reddit.com/r/AsahiLinux/comments/vs4qp1/how_to_uninstall/ 102 | 4. "Installing the Asahi Linux Alpha on my M1 Mac mini." Jeff Geerling. March 25, 2022. Accessed May 3, 2024. https://www.jeffgeerling.com/blog/2022/installing-asahi-linux-alpha-on-my-m1-mac-mini 103 | 5. "A native version of Chrome arrives for Arm-based Windows PCs." The Verge. March 26, 2024. Accessed October 30, 2024. https://www.theverge.com/2024/3/26/24112273/chrome-native-windows-on-arm-qualcomm-snapdragon 104 | 6. "Enabling Chromium to sync with Google Account." Stack Overflow. July 21, 2024. Accessed October 30, 2024. https://stackoverflow.com/questions/67459316/enabling-chromium-to-sync-with-google-account 105 | -------------------------------------------------------------------------------- /src/unix_distributions/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: UNIX Distributions 4 | 5 | android 6 | arch_linux 7 | asahi_linux 8 | chromium_os 9 | fedora 10 | macos 11 | raspberry_pi_os 12 | steamos 13 | -------------------------------------------------------------------------------- /src/unix_distributions/macos.rst: -------------------------------------------------------------------------------- 1 | macOS 2 | ===== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Window Positioning 7 | ------------------ 8 | 9 | Rectangle 10 | ~~~~~~~~~ 11 | 12 | `Rectangle `__ is a free and open source window tiling software for macOS. It adds native windows snapping similar to Windows. It also adds a variety of shortcuts for more customizations. [7] 13 | 14 | Shortcuts: 15 | 16 | - ``control`` + ``option`` + ``[left|right] arrow`` = Move a window to be on half of the screen. 17 | 18 | Rosetta 19 | ------- 20 | 21 | Rosetta 1 22 | ~~~~~~~~~ 23 | 24 | Rosetta 1 was used to run PowerPC programs on Intel. It was provided in MacOS X 10.4 Tiger through 10.6 Snow Leopard. [3] 25 | 26 | Rosetta 2 27 | ~~~~~~~~~ 28 | 29 | Rosetta 2 is used to run Intel programs on Arm. It was first added to macOS 11 Big Sur. [4] When an Intel program is executed, macOS will prompt the end-user to install Rosetta 2 if it is not installed already. [5] 30 | 31 | Manually install Rosetta 2: 32 | 33 | .. code-block:: sh 34 | 35 | $ softwareupdate --install-rosetta 36 | 37 | Enter an Intel-compatible shell on the CLI [6]: 38 | 39 | .. code-block:: sh 40 | 41 | $ arch-x86_64 zsh 42 | 43 | Xcode 44 | ----- 45 | 46 | Xcode Developer Tools is a suite of different utilities for doing development on macOS. It can be installed from the App Store. 47 | 48 | Common utilities [1]: 49 | 50 | - Command Line Tools = awk, git, make, sed, ssh, svc, tar, zip, and more. 51 | - SwiftUI = A user interface designer for Swift programs. 52 | - Terminal 2 = An advanced Termanial app that supports more colors, additional tabs, and full Unicode support. 53 | - Xcode IDE = A custom IDE tailored for development of apps on Apple products. 54 | 55 | Homebrew 56 | -------- 57 | 58 | Homebrew is an unofficial package manager for macOS. 59 | 60 | - Install: ``/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`` 61 | - Search for a program to see if it can be installed: ``brew search `` 62 | - Update cached repository metadata: ``brew update`` 63 | - Install a CLI utility: ``brew install `` 64 | - Install a GUI app: ``brew install --cask `` 65 | - Upgrade a package: ``brew upgrade `` 66 | - Upgrade all packages: ``brew upgrade`` 67 | - View all programs, and their dependencies, installed by Homebrew: ``brew list`` 68 | - View only the programs, not their dependencies, that were installed by Homebrew: ``brew leaves`` 69 | 70 | [2] 71 | 72 | History 73 | ------- 74 | 75 | - `Latest `__ 76 | - `< 2023.04.01 `__ 77 | 78 | Bibliography 79 | ------------ 80 | 81 | 1. "Xcode - Features." Apple Developer. Accessed January 12, 2021. https://developer.apple.com/xcode/features/ 82 | 2. "Homebrew The Missing Package Manager for macOS (or Linux)." Homebrew. Accessed January 13, 2021. https://brew.sh/ 83 | 3. "ARCHIVED: In Mac OS X, how do I run PowerPC applications with Rosetta?" University Information Technology Services. January 18, 2018. Accessed July 5, 2023. https://kb.iu.edu/d/azjd 84 | 4. "Apple ARM Macs: What you need to know now." July 15, 2020. Accessed July 5, 2023. https://www.computerworld.com/article/3566912/apple-arm-macs-what-you-need-to-know-now.html 85 | 5. "If you need to install Rosetta on your Mac." Apple Support. June 26, 2023. Accessed July 5, 2023. https://support.apple.com/en-us/HT211861 86 | 6. "How to Install x86_64 Homebrew Packages on Apple M1 MacBook." Medium. July 26, 2021. Accessed July 5, 2023. https://medium.com/mkdir-awesome/how-to-install-x86-64-homebrew-packages-on-apple-m1-macbook-54ba295230f 87 | 7. "How to get true window snapping in MacOS." ZDNET. July 5, 2023. Accessed July 31, 2023. https://www.zdnet.com/article/how-to-get-true-window-snapping-in-macos/ 88 | -------------------------------------------------------------------------------- /src/virtualization/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Virtualization 4 | 5 | containers 6 | cpu_emulation 7 | kubernetes_administration 8 | kubernetes_development 9 | kubernetes_security 10 | virtual_machines 11 | wine 12 | -------------------------------------------------------------------------------- /src/windows/display.rst: -------------------------------------------------------------------------------- 1 | Windows Display 2 | =============== 3 | 4 | .. contents:: Table of Contents 5 | 6 | HDR 7 | --- 8 | 9 | High Dynamic Range (HDR) media provides more realistic colors. HDR support requires a supported graphics device, driver, monitor, and video cable. [1] 10 | 11 | Enable HDR10 12 | ~~~~~~~~~~~~ 13 | 14 | Windows 10 and 11 natively support the open HDR10 standard. Starting with Windows 11, it supports auto HDR that converts a list of specific legacy games to use HDR. This is a feature first added to the Xbox Series consoles. [2] 15 | 16 | Windows 11 17 | 18 | - Settings (ms-settings:) > System > Display > Use HDR > Use HDR: On, HDR video streaming: On, Auto HDR: On 19 | 20 | Windows 10 21 | 22 | - Settings (ms-settings:) > System > Display > Use HDR: On 23 | 24 | Enable Dolby Vision 25 | ~~~~~~~~~~~~~~~~~~~ 26 | 27 | Dolby Vision is not natively supported on Windows. It requires installing various Microsoft Store apps on either Windows 10 or 11. [3] 28 | 29 | Microsoft Store apps: 30 | 31 | - `HEVC Video Extensions `__ = Paid. Required codec to decode Dolby Vision video files. 32 | - `Dolby Vision Extensions `__ = Free. Required to add Dolby Vision support to Windows. 33 | - `Dolby Access `__ = Free trial. Optional for playing Dolby Vision video files. This also provides support for Digital Theater Sound (DTS) and Dolby Atmos surround sound. 34 | 35 | History 36 | ------- 37 | 38 | - `Latest `__ 39 | 40 | Bibliography 41 | ------------ 42 | 43 | 1. "How to enable High Dynamic Range?" Intel. Accessed February 6, 2023. https://www.intel.com/content/www/us/en/support/articles/000032112/graphics.html 44 | 2. "Configure your console for FPS boost and auto HDR." Xbox Support. Accessed February 6, 2023. https://support.xbox.com/en-US/help/hardware-network/display-sound/fps-boost-and-auto-hdr 45 | 3. "Get Dolby Vision instead of HDR10 on Windows 10?" Linus Tech Tips Forum. December 8, 2022. Accessed February 6, 2023. https://linustechtips.com/topic/1145733-get-dolby-vision-instead-of-hdr10-on-windows-10/page/2/ 46 | -------------------------------------------------------------------------------- /src/windows/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | :caption: Windows 4 | 5 | display 6 | editions 7 | performance_tuning 8 | security 9 | storage 10 | virtualization 11 | -------------------------------------------------------------------------------- /src/windows/security.rst: -------------------------------------------------------------------------------- 1 | Windows Security 2 | ================ 3 | 4 | .. contents:: Table of Contents 5 | 6 | Antivirus 7 | ---------- 8 | 9 | Microsoft Defender Antivirus 10 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 11 | 12 | This antivirus is free and available for all versions of Windows starting with Windows XP. It was previously named Windows Defender Antivirus and Windows Defender. As of Windows 8.1, it is installed and enabled by default. [1] 13 | 14 | Disable 15 | ^^^^^^^ 16 | 17 | If using another antivirus program or if required for testing, it may be desired to disable Windows Defender. 18 | 19 | **Manually** 20 | 21 | - Real-time protection 22 | 23 | - Windows 11 24 | 25 | - Settings (ms-settings:) > Privacy & security > Windows Security > Virus & threat protection > Manage settings > Real-time protection: Off, Cloud-delivered protection: Off, Automatic sample submission: Off, and Tamper Protection: Off 26 | 27 | - Windows 10 28 | 29 | - Settings (ms-settings:) > Update & Security > Windows Security > Virus & threat protection > Manage settings > Real-time protection: Off 30 | 31 | - Scheduled tasks 32 | 33 | - Windows 11 and 10 34 | 35 | - Task Scheduler (taskschd.msc) > Task Scheduler (Local) > Task Scheduler Library > Microsoft > Windows > Windows Defender 36 | 37 | - Select each task and either `Disable` or `Delete` them: `Windows Defender Cache Maintenance`, `Windows Defender Cleanup`, `Windows Defender Scheduled Scan`, and `Windows Defender Verification`. [2] 38 | 39 | **Automatically** 40 | 41 | - Windows 10 42 | 43 | - Download and extract `Debloat Windows 10 scripts `__. 44 | 45 | :: 46 | 47 | PS C:\Windows\system32> Invoke-WebRequest -Uri https://github.com/W4RH4WK/Debloat-Windows-10/archive/master.zip -OutFile Debloat-Windows-10.zip 48 | PS C:\Windows\system32> Expand-Archive Debloat-Windows-10.zip 49 | PS C:\Windows\system32> cd .\Debloat-Windows-10\Debloat-Windows-10-master\scripts\ 50 | 51 | - Allow the PowerShell scripts to be executable. 52 | 53 | :: 54 | 55 | PS C:\Windows\system32> Set-ExecutionPolicy Unrestricted -Scope CurrentUser 56 | PS C:\Windows\system32> ls -Recurse *.ps*1 | Unblock-File 57 | 58 | - Disable Windows Defender. 59 | 60 | :: 61 | 62 | PS C:\Windows\system32> .\disable-windows-defender.ps1 63 | 64 | User Account Control (UAC) 65 | -------------------------- 66 | 67 | UAC ensures that all applications are run as a normal user account with no escalated privileges. When an application tries to run as Administrator, UAC will prompt the user and ask if they want to run with Administrator privileges. [3] This feature was first introduced in Windows Vista. [4] 68 | 69 | Disable 70 | ~~~~~~~ 71 | 72 | For users who often need to use the Administrator account, it may be desired to disable UAC entirely. 73 | 74 | - Windows 11 and 10 75 | 76 | - Control Panel (Control Panel) > User Accounts > User Accounts > Change User Account Control settings > Never notify 77 | 78 | Process Monitor 79 | --------------- 80 | 81 | Usage 82 | ~~~~~ 83 | 84 | Process Monitor is an official tool from Microsoft. It is useful to see what a process is doing for security or troubleshooting purposes. Newer versions also support Linux. 85 | 86 | - Download and extract `Process Monitor `__. 87 | - Run ``Procmon64.exe``. 88 | - By default, it captures all events immediately. Clear this before managing filters. 89 | 90 | - File > Capture Events 91 | - Edit > Clear Display 92 | 93 | - Add one or more filters using the `example filters <#example-filters>`__ as a starting point. 94 | - Press the Capture button (an arrow facing right). Inside the icon, a sub-icon will change from a pause icon (two bars) to a recording icon (red dot). 95 | - When done, press the Capture button again to pause the montioring. 96 | - Save the output in a common text file format for easier parsing. 97 | 98 | - File > Save... > Format: Comma-Separated Values (CSV) > OK 99 | 100 | Example Filters 101 | ~~~~~~~~~~~~~~~ 102 | 103 | Add filter for certain registry file changes (if you know what to look for). 104 | 105 | - Filter > Filter... 106 | 107 | - Path, Contains, (enter text to look for), then: Include > Add 108 | - Apply 109 | 110 | Add a filter for all registry writes. Ignore common Windows services that access the registry. 111 | 112 | - Filter > Filter... 113 | 114 | - Operation, is, RegCreateKey, then: Include > Add 115 | - Operation, is, RegSetValue, then: Include > Add 116 | - Process Name, is, FMService64.exe > then > Exclude 117 | - Process Name, is, svchost.exe > then > Exclude 118 | - Process Name, is, wermgr.exe > then > Exclude 119 | - Process Name, is, Widgets.exe > then > Exclude 120 | - Apply 121 | 122 | Add a filter for all registry access. 123 | 124 | - Filter > Filter... 125 | 126 | - Operation, begins with, Reg, then: Include > Add 127 | - Apply 128 | 129 | Add a filter for all file writes. 130 | 131 | - Filter > Filter... 132 | 133 | - Operation, is, CreateFile, then: Include > Add 134 | - Operation, is, WriteFile, then: Include > Add 135 | - Apply 136 | 137 | Add a filter to see everything a process is doing. 138 | 139 | - Filter > Filter... 140 | 141 | - Process Name, is, (the EXE name), then: Include > Add 142 | - Apply 143 | 144 | - Options > Select Columns... > Event Details > (check "Sequence Number") > OK 145 | 146 | Add a filter to see everything a MSI installer is doing. 147 | 148 | - Filter > Filter... 149 | 150 | - Process Name, is, msiexec.exe, then: Include > Add 151 | - Apply 152 | 153 | History 154 | ------- 155 | 156 | - `Latest `__ 157 | 158 | Bibliography 159 | ------------ 160 | 161 | 1. "I already have Windows Defender – why do I need another antimalware tool?" Panda Security Mediacenter. July 15, 2021. Accessed August 18, 2021. https://www.pandasecurity.com/en/mediacenter/tips/defender-antimalware-tool/ 162 | 2. "how to cancel windows defender automatic scans?" Windows 10 Help Forums. June 8, 2016. Accessed August 18, 2021. https://www.tenforums.com/antivirus-firewalls-system-security/52486-how-cancel-windows-defender-automatic-scans.html 163 | 3. "User Account Control." Microsoft Docs. December 3, 2021. Accessed April 7, 2022. https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/user-account-control-overview 164 | 4. "User Account Control." Fandom Microsoft Wiki. June 13, 2017. Accessed April 7, 2022. https://microsoft.fandom.com/wiki/User_Account_Control 165 | -------------------------------------------------------------------------------- /src/windows/virtualization.rst: -------------------------------------------------------------------------------- 1 | Windows Virtualization 2 | ====================== 3 | 4 | .. contents:: Table of Contents 5 | 6 | Windows Subsystem for Linux (WSL) 7 | --------------------------------- 8 | 9 | WSL 1 translated Linux system calls to Windows. This is essentially the opposite of the Wine project that is used to translate Windows system calls to Linux. Due to performance, stability, and compatibility concerns, WSL 1 is no longer used. WSL 2 is used by default. It creates a Hyper-V virtual machine instead. WSL is supported on Windows 10 and 11. 10 | 11 | Open a Command Prompt as the Administrator user and then install WSL. This will enable the feature and install Ubuntu. 12 | 13 | :: 14 | 15 | C:\Windows\System32>wsl --install 16 | 17 | Run this command to view the list of Linux distributions that can be installed. 18 | 19 | :: 20 | 21 | C:\Windows\System32>wsl --list --online 22 | 23 | This is the list of officially supported Linux distributions: 24 | 25 | - Debian 26 | - Kali Linux 27 | - Oracle Linux 28 | - SUSE Linux Enterprise Server (SLES) 29 | - Ubuntu 30 | 31 | Optionally, select another operating system to install. 32 | 33 | :: 34 | 35 | C:\Windows\System32>wsl --install -d 36 | 37 | Reboot to finish the installation. 38 | 39 | Then open a Command Prompt and run either ``bash`` or ``wsl`` to open a Linux terminal. [1] Alternatively, there will also be drop-down box in the Command Prompt that will add an "Ubuntu" option to open it up using the UI. If there are any errors on the first try, close the window and then try to launch WSL again. 40 | 41 | On Windows 11, there is a false-positive report from the control flow guard (CFG) protection that prevents WSL 2 from starting. Disable it to be able to use WSL 2. [2] 42 | 43 | - Windows Security (windowsdefender:) > App & browser control > Exploit protection settings > Control flow guard (CFG): Off by default 44 | 45 | Fedora 46 | ~~~~~~ 47 | 48 | There are no official images of Fedora for WSL. 49 | 50 | Automatic Set Up 51 | ^^^^^^^^^^^^^^^^ 52 | 53 | - Install and open the unofficial `Fedora WSL `__ image from the Microsoft Store. The source code can be found `here `__. [3] 54 | 55 | Manual Set Up 56 | ^^^^^^^^^^^^^ 57 | 58 | It is possible to use a container image for the root file system of Fedora and then import it into WSL 2. [4] 59 | 60 | Run a Fedora container and then save the root file system. 61 | 62 | :: 63 | 64 | C:\Users\ docker run --name fedora40 fedora:40 65 | C:\Users\ docker export -o fedora-40-rootfs.tar fedora40 66 | 67 | Import the root file system. 68 | 69 | :: 70 | 71 | C:\Users\> mkdir $HOME\wsl\fedora 72 | C:\Users\> wsl --import fedora $HOME\wsl\fedora $HOME\Downloads\fedora-40-rootfs.tar 73 | C:\Users\> wsl -d fedora 74 | 75 | Configure DNS resolvers. 76 | 77 | :: 78 | 79 | [root@ fedora]# echo -e "[network]\ngenerateResolvConf = false" > /etc/wsl.conf 80 | [root@ fedora]# exit 81 | C:\Users\> wsl -t fedora 82 | C:\Users\> wsl -d fedora 83 | [root@ fedora]# unlink /etc/resolv.conf 84 | [root@ fedora]# echo nameserver 1.1.1.1 > /etc/resolv.conf 85 | 86 | Upgrade Fedora. 87 | 88 | :: 89 | 90 | [root@ fedora]# dnf upgrade 91 | 92 | Install the minimum packages required for user accounts and WSL mounts to work. 93 | 94 | :: 95 | 96 | [root@ fedora]# dnf install cracklib-dicts passwd util-linux 97 | 98 | Configure a new user. 99 | 100 | :: 101 | 102 | [root@ fedora]# useradd -G wheel 103 | [root@ fedora]# passwd 104 | [root@ fedora]# printf "\n[user]\ndefault = \n" | sudo tee -a /etc/wsl.conf 105 | [root@ fedora]# exit 106 | C:\Users\> wsl -t fedora 107 | 108 | Verify that the new user works. 109 | 110 | :: 111 | 112 | C:\Users\> wsl -d fedora -u 113 | [@ fedora]$ whoami 114 | 115 | [@ fedora]$ sudo whoami 116 | root 117 | 118 | In PowerShell, configure the WSL distribution name and the user ID. 119 | 120 | :: 121 | 122 | C:\Users\> Get-ItemProperty Registry::HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\*\ DistributionName | Where-Object -Property DistributionName -eq fedora | Set-ItemProperty -Name DefaultUid -Value 1000 123 | 124 | Fix permission issues related to user accounts. 125 | 126 | :: 127 | 128 | [@ fedora]$ sudo dnf reinstall shadow-utils 129 | 130 | Enable ping support. 131 | 132 | - Fedora: 133 | 134 | :: 135 | 136 | [@ fedora]$ sudo dnf install procps-ng iputils 137 | [@ fedora]$ sudo sysctl -w net.ipv4.ping_group_range="0 2000" 138 | 139 | - Windows: 140 | 141 | :: 142 | 143 | C:\Users\> echo [wsl2] >> .wslconfig 144 | C:\Users\> echo kernelCommandLine = sysctl.net.ipv4.ping_group_range=\"0 2000\" >> .wslconfig 145 | 146 | Enable manual pages for new package installations. 147 | 148 | :: 149 | 150 | [@ fedora]$ grep -v nodocs /etc/dnf/dnf.conf | sudo tee /etc/dnf/dnf.conf 151 | [@ fedora]$ sudo dnf install man man-pages 152 | 153 | Optionally re-install existing packages to install their manual pages. 154 | 155 | :: 156 | 157 | [@ fedora]$ for pkg in $(dnf repoquery --installed --qf "%{name}"); do sudo dnf reinstall -qy $pkg; done 158 | 159 | Optionally export the fully configured WSL file system. 160 | 161 | :: 162 | 163 | [@ fedora]$ sudo dnf clean all 164 | [@ fedora]$ exit 165 | C:\Users\> wsl --export fedora C:\Users\\Downloads\fedora-40-wsl.tar 166 | 167 | History 168 | ------- 169 | 170 | - `Latest `__ 171 | 172 | Bibliography 173 | ------------ 174 | 175 | 1. "Install Linux on Windows with WSL." Microsoft Learn Technical documentation. January 12, 2023. Accessed February 6, 2023. https://learn.microsoft.com/en-us/windows/wsl/install 176 | 2. "The operation could not be started because a required feature is not installed #4951." GitHub microsoft/WSL. May 23, 2022. Accessed February 6, 2023. https://github.com/microsoft/WSL/issues/4951 177 | 3. "How to install Fedora on WSL for Windows 10 and Windows 11." Windows Central. July 8, 2023. Accessed April 21, 2024. https://www.windowscentral.com/software-apps/how-to-install-fedora-on-wsl-for-windows-10-and-windows-11 178 | 4. "Install Fedora 37 or earlier on Windows Subsystem for Linux (WSL)." DEV Community Jonathan Bowman. October 29, 2022. Accessed April 21, 2024. https://dev.to/bowmanjd/install-fedora-on-windows-subsystem-for-linux-wsl-4b26 179 | --------------------------------------------------------------------------------