caharkness/documentation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit with existing docs

Browse Source
This commit is contained in:
Conner Harkness 2024-10-01 07:50:52 -06:00
parent 21ca088aee
commit da86b0597a
12 changed files with 619 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
Examples/Bash/Port Forwarding.md Normal file
View File

@ -0,0 +1,184 @@
## Starting
---
As with every shell script that we intend to run using Bash
#!/bin/bash
## reset_iptables ()
---
A function used to reset the state of iptables so that we are guaranteed no rules that have gone unaccounted for:
reset_iptables () {
iptables -F;
iptables -X;
iptables -t nat -F;
iptables -t nat -X;
iptables -t mangle -F;
iptables -t mangle -X;
iptables -t raw -F;
iptables -t raw -X;
iptables -t security -F;
iptables -t security -X;
iptables -P INPUT ACCEPT;
iptables -P FORWARD ACCEPT;
iptables -P OUTPUT ACCEPT;
}
!!! warning "Potential Security Risk"
The above function when called will remove any existing iptables rules in place.
### Example
---
The call to the function is pretty straightforward. Calling it clears any rules defined in iptables.
reset_iptables;
## forward_internet ()
---
A function used to forward requests from clients whose gateway is defined as this router's IP address to this machine's own Internet connection interface:
forward_internet () {
CLIENT_NET=$1;
INET_IFACE=$2;
iptables -t nat -A POSTROUTING -o $INET_IFACE -j MASQUERADE;
iptables -I FORWARD -o $INET_IFACE -s $CLIENT_NET -j ACCEPT;
iptables -I INPUT -s $CLIENT_NET -j ACCEPT;
}
### Examples
---
To act as a gateway to the Internet for other devices on the network sending packets from `192.168.1.x`:
forward_internet 192.168.1.0/24 wlan0;
## forward_port ()
---
A function used to forward incoming connections from an outside interface and port to an inside address & port destination and establish a path back for the response:
forward_port () {
OUTSIDE_INTERFACE=$1;
OUTSIDE_PORT=$2;
INSIDE_ADDRESS=$3;
INSIDE_PORT=$4;
sysctl net.ipv4.conf.all.forwarding=1 > /dev/null;
sysctl net.ipv6.conf.all.forwarding=1 > /dev/null;
iptables -A PREROUTING -t nat -p tcp -i $OUTSIDE_INTERFACE --dport $OUTSIDE_PORT -j DNAT --to-destination $INSIDE_ADDRESS:$INSIDE_PORT;
iptables -A POSTROUTING -t nat -p tcp -d $INSIDE_ADDRESS --dport $INSIDE_PORT -j MASQUERADE;
echo "$OUTSIDE_INTERFACE:$OUTSIDE_PORT -> $INSIDE_ADDRESS:$INSIDE_PORT";
}
## Usage
---
reset_iptables;
forward_internet 10.44.7.0/24 wlan0;
forward_port tun0 8006 10.44.7.159 8006;
forward_port tun0 8007 10.44.7.157 8006;
forward_port tun0 7860 10.44.7.103 7860;
forward_port tun0 7861 10.44.7.100 7861;
forward_port tun0 7862 10.44.7.100 7862;
forward_port tun0 22001 10.44.7.111 22;
forward_port tun0 22002 10.44.7.100 22;
forward_port tun0 22003 10.44.7.105 22;
forward_port tun0 80 10.44.7.111 80;
forward_port tun0 443 10.44.7.111 443;
forward_port tun0 35566 10.44.7.112 35566;
forward_port wlan0 8006 10.44.7.159 8006;
forward_port wlan0 8007 10.44.7.157 8006;
forward_port tun0 8033 10.44.7.114 80;
forward_port tun0 25 10.44.7.102 25;
forward_port tun0 587 10.44.7.102 587;
forward_port tun0 465 10.44.7.102 465;
## forward.sh
---
``` bash title="forward.sh"
#!/bin/bash
reset_iptables () {
iptables -F;
iptables -X;
iptables -t nat -F;
iptables -t nat -X;
iptables -t mangle -F;
iptables -t mangle -X;
iptables -t raw -F;
iptables -t raw -X;
iptables -t security -F;
iptables -t security -X;
iptables -P INPUT ACCEPT;
iptables -P FORWARD ACCEPT;
iptables -P OUTPUT ACCEPT;
}
forward_internet () {
CLIENT_NET=$1;
INET_IFACE=$2;
iptables -t nat -A POSTROUTING -o $INET_IFACE -j MASQUERADE;
iptables -I FORWARD -o $INET_IFACE -s $CLIENT_NET -j ACCEPT;
iptables -I INPUT -s $CLIENT_NET -j ACCEPT;
}
forward_port () {
OUTSIDE_INTERFACE=$1;
OUTSIDE_PORT=$2;
INSIDE_ADDRESS=$3;
INSIDE_PORT=$4;
sysctl net.ipv4.conf.all.forwarding=1 > /dev/null;
sysctl net.ipv6.conf.all.forwarding=1 > /dev/null;
iptables -A PREROUTING -t nat -p tcp -i $OUTSIDE_INTERFACE --dport $OUTSIDE_PORT -j DNAT --to-destination $INSIDE_ADDRESS:$INSIDE_PORT;
iptables -A POSTROUTING -t nat -p tcp -d $INSIDE_ADDRESS --dport $INSIDE_PORT -j MASQUERADE;
echo "$OUTSIDE_INTERFACE:$OUTSIDE_PORT -> $INSIDE_ADDRESS:$INSIDE_PORT";
}
reset_iptables;
forward_internet 192.168.1.0/24 wlan0;
forward_port tun0 8006 10.44.7.159 8006;
forward_port tun0 8007 10.44.7.157 8006;
forward_port tun0 7860 10.44.7.103 7860;
forward_port tun0 7861 10.44.7.100 7861;
forward_port tun0 7862 10.44.7.100 7862;
forward_port tun0 22001 10.44.7.111 22;
forward_port tun0 22002 10.44.7.100 22;
forward_port tun0 22003 10.44.7.105 22;
forward_port tun0 80 10.44.7.111 80;
forward_port tun0 443 10.44.7.111 443;
forward_port tun0 35566 10.44.7.112 35566;
forward_port wlan0 8006 10.44.7.159 8006;
forward_port wlan0 8007 10.44.7.157 8006;
forward_port tun0 8033 10.44.7.114 80;
forward_port tun0 25 10.44.7.102 25;
forward_port tun0 587 10.44.7.102 587;
forward_port tun0 465 10.44.7.102 465;
```
Devices on any network that have a `192.168.1.x` can make this router a gateway and connect to the Internet:
Requests made to this router from interface `tun0` for port `8006` will be forwarded to `10.44.7.159:8006`:
forward_port tun0 8006 10.44.7.159 8006;

21
Examples/Debian/Enable Serial Console.md Normal file
View File

@ -0,0 +1,21 @@
###### Procedure
1. Open `/etc/default/grub` in nano, e.g.
nano /etc/default/grub
2. Modify the line `GRUB_CMDLINE_LINUX_DEFAULT` to include `console=ttyS0`, e.g.
GRUB_CMDLINE_LINUX_DEFAULT="quiet console=ttyS0"
3. Update grub via the `update-grub` command
4. If using Proxmox, be sure to add a hardware serial port
!!! info "Note"
If done correctly, your Debian virtual machine in Proxmox will have a text console accessible via xterm.js
###### Sources
<http://notesofaprogrammer.blogspot.com/2020/05/enabling-serial-console-on-debian-linux.html>

77
Examples/Debian/Install Apache.md Normal file
View File

@ -0,0 +1,77 @@
###### About
<https://httpd.apache.org/>
###### Procedure
1. Sign in as root user
2. Run `apt install apache2`
3. Run `a2enmod ssl` to enable SSL/TLS functionality
4. Run `a2enmod rewrite` to allow address rewriting
5. Run `a2enmod proxy && a2enmod proxy_http` to enable reverse proxies
!!! warning "Warning"
By default, Apache creates a virtual host and enables a site hosted at `/var/www/html`. Follow the recommendations below to get a
###### Recommendations
1. Run `rm /etc/apache2/sites-enabled/*` to remove any existing symbolic links to virtual host configurations
2. Run `cd /var/www` to navigate to where sites are suggested to be stored
3. Delete the `html` directory via `rm -rf html`
###### New Site
!!! info "Info"
In the following example, we will create a virtual host that responds only to requests made for `docs.caharkness.com` on port 443. The virtual host will be configured as a reverse proxy, exposing the http features of an application running locally to the requestor, all while handing the TLS handshake and keeping the transmission between Apache and the requestor secure.
1. Create a directory to contain virtual hosts in, e.g.
mkdir sites && cd sites
2. Create a new directory within the newly created container for our virtual host, e.g.
```
mkdir docs.caharkness.com && cd docs.caharkness.com
```
3. Produce a file named `vhost.conf` with the following lines:
``` title="vhost.conf"
<VirtualHost *:443>
ServerName docs.caharkness.com
DocumentRoot /var/www/sites/docs.caharkness.com
SSLEngine on
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
# Uncomment if applicable:
# SSLCertificateChainFile /etc/apache2/ssl.crt/server-ca.crt
SSLOptions +StdEnvVars
<Directory __SITE_DIR__>
Options -Indexes
AllowOverride All
</Directory>
ProxyPass "/" "http://127.0.0.1:8080/"
ProxyPassReverse "/" "http://127.0.0.1:8080/"
</VirtualHost>
```
!!! info "Info"
1. Acquiring signed certificates is not covered in this example, but if you know the paths to your certificate, key, and chain files, you may specify them above. Otherwise, we default to using Debian's internal "snakeoil" certificates.
4. Run `ln -s vhost.conf /etc/apache2/sites-enabled/docs.caharkness.com-vhost.conf` to link the site's `vhost.conf` to where Apache looks by default for virtual hosts to serve
5. Run `systemctl reload apache2` to gracefully reload changes without interrupting ongoing requests

57
Examples/Debian/Install Docker.md Normal file
View File

@ -0,0 +1,57 @@
###### Procedure
1. Run `apt udpate`
2. Install the following:
apt install ca-certificates curl
3. Create the keyrings directory with correct permissions:
install -m 0755 -d /etc/apt/keyrings
4. Save the current key from Docker:
curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
5. Allow everybody to read the `docker.asc` key:
chmod a+r /etc/apt/keyrings/docker.asc
6. Add the official Docker repository to apt:
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
7. Run `apt update` again
8. Install the required Docker packages:
apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
9. Test that Docker is installed via `docker --version`
10. Test the Docker `hello-world` image:
docker run hello-world
###### Administration
1. Create a volume for Portainer:
docker volume create portainer_data
2. Install Portainer:
docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:2.20.3
**Note:** The version number `2.20.3` is current at the time of writing but may change in the future
3. Connect to Portainer's web interface by visiting port 9443 in the address bar, e.g. <https://debian-host:9443/>
###### Extras
1. If installing a Microsoft SQL Server for Linux container running Ubuntu, create a volume that maps to `/var/opt/mssql/data` in the container. The databases you create will persist across recreating or duplicating/editing. No additional configuration is needed.
###### Sources
<https://docs.docker.com/engine/install/debian/>

25
Examples/Debian/Install MariaDB.md Normal file
View File

@ -0,0 +1,25 @@
###### About
<https://mariadb.org/> — A free and open source alternative to MySQL
###### Procedure
1. Run `apt install mariadb-server` to install MariaDB Server
2. Run `mysql_secure_installation` to perform the intial setup
3. Enter the MariaDB shell via running `mysql -u root -p` and supplying your password
4. Run the following query to enable the root user for all hosts:
```mysql title="MariaDB"
grant all privileges on *.* to 'root'@'%' identified by 'password' with grant option;
```
Congratulations, you can now connect to the local database through other applications, such as Python scripts and Adminer.
###### Sources
<https://www.digitalocean.com/community/tutorials/how-to-install-mariadb-on-ubuntu-20-04>
<https://community.flexera.com/t5/Software-Vulnerability-Manager/How-to-grant-root-account-remote-access-to-MariaDB/ta-p/4967>

53
Examples/Debian/Install Node.js.md Normal file
View File

@ -0,0 +1,53 @@
###### About
<https://nodejs.org/en>
###### Procedure
1. Sign in as root user
2. Run `apt install nodejs`
!!! info "Note"
This command may install an older version of Node.
3. Run `node --version` to verify the installed version of Node.js
4. Run `apt install npm` to install the Node package manager
5. Run `npm install -g n` to *globally* install the `n` Node version manager
6. Run `n latest` to fetch and install the latest version of Node.js
###### Optional
1. Install the PM2 daemon process manager globally via:
```
npm install -g pm2
```
This package allows daemonizing Node projects or shell scripts without the need to learn System V run levels, "init," or systemd services. For example, if we have a shell script that spawns a Java or Python-written server, you can use PM2 to host it:
```sh title="/root/myapp/myapp.sh"
#!/bin/bash
cd /root/myapp
source ./venv/bin/activate
python3 -u myapp.py
```
1. Run `cd /root/myapp`
2. Run `pm2 start myapp.sh` to daemonize `myapp.sh` with PM2
3. Run `pm2 startup` to enable running PM2 at system startup
4. Run `pm2 save` to save the current process list
To view a list of all daemonized processes, run `pm2 list`. If your application crashes, PM2 will automatically restart your process, but may fail if the application is crashing in rapid succession. To view why, run `pm2 log myapp`.
###### About PM2
<https://pm2.keymetrics.io/>

53
Examples/Debian/Install Python.md Normal file
View File

@ -0,0 +1,53 @@
###### About
<https://www.python.org/>
###### Procedure
1. Sign in as root user
2. Run `apt install python3 python3-venv` to install Python 3.x, whichever version may be the latest
!!! info "Info"
The package `python3-venv` is included because it is in best practice to containerize Python projects and keep their dependencies isolated in environments where more than one application may be hosted
3. Run `python3 --version` to identify the version of Python installed
###### New Projects
1. Run `mkdir myapp && cd myapp` to create a new home for our Python project
2. Run `python3 -m venv venv` to create a virtual environment (venv)
3. Run `source ./venv/bin/activate` to activate
!!! info "Info"
Calling `python3` or `pip3` is no longer necessary. The alias `python` is symbolically linked to the correct executable and a copy of pip is included within the virtual environment. Installing packages using `pip install -r requirements.txt` or `pip install x` will install the downloaded libraries and modules local to this environment!
4. Run `python -u myapp.py` to run a script using our venv
!!! tip "Tip"
The `-u` in `python -u myapp.py` is instructing the Python interpreter to run in unbuffered output mode
###### Optional
1. Daemonize the Python application
1. Create a new shell script via `nano myapp.sh`
```sh title="/root/myapp/myapp.sh"
#!/bin/bash
cd /root/myapp
source ./venv/bin/activate
python -u myapp.py
```
1. Run `chmod +x myapp.sh`
2. Learn about [installing Node.js and PM2](?q=Node.js)
3. Run `pm2 start myapp.sh && pm2 save`

39
Examples/Debian/Joining a LAN.md Normal file
View File

@ -0,0 +1,39 @@
###### Procedure
1. Sign in as root user
2. Open `/etc/network/interfaces` with nano, e.g.
```
nano /etc/network/interfaces
```
3. Ensure something similar to the following exists for the primary adapter:
```
allow-hotplug eth0
iface eth0 inet static
address 192.168.1.100/24
gateway 192.168.1.1
dns-nameservers 192.168.1.1
```
!!! info "Note"
Substitute `eth0` for the true interface name of the device that will connect you to the LAN
* The `/24` is the CIDR format of having a netmask of `255.255.255.0`. The non-CIDR equivalent is:
address 192.168.1.100
netmask 255.255.255.0
# .../16 = 255.255.0.0
# .../21 = 255.255.248.0
4. Save and run `systemctl restart networking && ifup eth0`
5. Run `ip address` and inspect the output for changes
###### Sources
<https://wiki.debian.org/NetworkConfiguration>

23
Examples/Debian/Restore Old Interface Names.md Normal file
View File

@ -0,0 +1,23 @@
###### Procedure
1. Sign in as root user
2. Open `/etc/default/grub` with nano, e.g.
```
nano /etc/default/grub
```
3. Add `net.ifnames=0` to the `GRUB_CMDLINE_LINUX_DEFAULT` option, e.g.
```
GRUB_CMDLINE_LINUX_DEFAULT="... net.ifnames=0"
```
!!! warning "Caution"
Be mindful of the existing options set for `GRUB_CMDLINE_LINUX_DEFAULT`. Append `net.ifnames=0` to the end of them if they exist. The `...` in the example above indicates an indeterminate amount of options irrelevant to the guide.
4. Save and run `update-grub && reboot`
5. Finally, run `ip address` to inspect network interfaces for names like `eth0` and `eth1`

15
Examples/Debian/Why Debian.md Normal file
View File

@ -0,0 +1,15 @@
# Why Debian?
###### About
<https://www.debian.org/intro/about>
###### Reasons to Adopt
* **Debian is the "grand daddy" of many common Linux distributions today.** Its age implies a long time of development, understanding, and implementation.
* **It's extremely easy to install and use.** Time is valuable and can easily be wasted setting up and configuring other options. Debian includes the `apt` package manager, making the installation of key software a one or two liner.
* **It's not Ubuntu.** Ubuntu is moving away from APT in favor of Canonical's own Snap, which creates a division in package maintenance efforts as well as unnecessary confusion for the end user when looking for where to source new software.
* **It's dangerous.** Debian does not stop you from using the root user, unlike some distributions. If you wish to spin up a single user server environment and execute everything as root, you can. There's no need to ask for permission to do things on your own server or virtual machine.

7
Examples/Docker/Example PHP Webserver.md Normal file
View File

@ -0,0 +1,7 @@
###### Dockerconfig
FROM debian:12
MAINTAINER caharkness version 1.0
RUN apt update && apt install -y php8.2
EXPOSE 80/tcp
CMD cd /root/php && php -S 0.0.0.0:80 -c php.ini index.php

65
Examples/Python/MariaDB Access.md Normal file
View File

@ -0,0 +1,65 @@
###### Procedure
1. Run `pip install mysql-connector-python` to install the required dependency
###### Code
```py title="db.py"
# Updated 2024-02-08
import mysql.connector
import time
conn = None
conn_config = {
"user": "root",
"password": "password",
"host": "127.0.0.1",
"database": "my_first_database",
"raise_on_warnings": True
}
# Create a method that handles connecting and retrying:
def connect_to_mysql(config, attempts=3, delay=2):
attempt = 1
while attempt < attempts + 1:
try:
return mysql.connector.connect(**config)
except (mysql.connector.Error, IOError) as err:
if (attempts is attempt):
print("Error connecting to DB IO Error")
return None
print(f"Error connecting to DB {err}")
# progressive reconnect delay
time.sleep(delay ** attempt)
attempt += 1
return None
#
def get_connection():
global conn
if conn is None:
conn = connect_to_mysql(conn_config, attempts=3)
if not conn.is_connected():
conn.reconnect(attempts=5, delay=1)
return conn
def query(query_string, query_args=None, retry=True):
c = get_connection()
try:
if c.is_connected():
with c.cursor(prepared=True, dictionary=True) as cur:
result = cur.execute(query_string, params=query_args, multi=True)
rows = cur.fetchall()
c.commit()
cur.close()
return rows
except Exception as x:
print("Exception!")
```