jb-vpn.uk Wiki - User contributions [en]

Documentation:Wiki Deployment

2026-05-16T14:45:30Z

Josh: Updated documentation from markdown files

Production wikis run on this VPS under <code>/var/www/wiki.jb/</code>.

== Stack ==

{| class="wikitable"
|-
| Service || Container || Public URL || Upstream
|-
| Main wiki || <code>wiki-mediawiki</code> || https://wiki.jb-vpn.uk || <code>127.0.0.1:8010</code>
|-
| Werbs wiki || <code>wiki-werbs-mediawiki</code> || https://werbs-wiki.jb-vpn.uk || <code>127.0.0.1:8011</code>
|-
| Database || <code>wiki-mariadb</code> || (internal) || <code>127.0.0.1:3307</code>
|}

* '''MediaWiki version''': 1.44 (Docker image <code>mediawiki:1.44</code>)

* '''Edge proxy''': Caddy (<code>/etc/caddy/Caddyfile</code>) terminates HTTPS and proxies to the containers

* '''Config on host''': <code>wiki/LocalSettings.php</code>, <code>werbs-wiki/LocalSettings.php</code> (mounted read-only; group <code>www-data</code> must be able to read)

* '''Uploads''': <code>wiki/images/</code>, <code>werbs-wiki/images/</code>

== Daily operations ==

<pre class="lang-bash">
cd /var/www/wiki.jb
docker compose ps
docker compose logs -f wiki
docker compose restart wiki werbs-wiki
</pre>

Upload documentation from the VPS:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload -y
python3 /root/wiki_manager.py --update-main-page -y
</pre>

Optional uploads without public HTTPS round-trip:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload -y --wiki-url http://127.0.0.1:8010
</pre>

== Email ==

Outbound mail uses Fastmail SMTP (configured in each <code>LocalSettings.php</code>: <code>$wgSMTP</code>, <code>$wgPasswordSender</code>, <code>$wgEmergencyContact</code>). After editing settings on the host, ensure permissions remain <code>640</code> and group <code>www-data</code>.

== Backups ==

<pre class="lang-bash">
cd /var/www/wiki.jb
bash scripts/backup-wikis.sh
</pre>

Creates <code>backups/YYYY-MM-DD/</code> with <code>mediawiki.sql</code>, <code>mediawiki_werbs.sql</code>, and <code>wiki-images.tar.gz</code>. Deletes backup folders older than 30 days (<code>RETENTION_DAYS=0</code> to disable pruning).

Weekly cron (root):

<pre class="lang-cron">
0 3 '' '' 0 /var/www/wiki.jb/scripts/backup-wikis.sh >> /var/log/wiki-backup.log 2>&1
</pre>

== Maintenance ==

<pre class="lang-bash">
cd /var/www/wiki.jb
source .env
docker compose exec -T wiki php maintenance/run.php update --quick --conf /var/www/html/LocalSettings.php
docker compose exec -T werbs-wiki php maintenance/run.php update --quick --conf /var/www/html/LocalSettings.php
</pre>

Logos after image restores: <code>bash scripts/fix-logos.sh</code>

== Extensions ==

The VPS <code>LocalSettings.php</code> files use the '''default MediaWiki 1.44 extension set''' from the installer (skins only unless you add more). Content was imported from the NAS farm; per-wiki farm files (<code>LocalSettings_wiki.php</code>, <code>LocalSettings_werbs-wiki.php</code>) are not on this server.

To restore NAS-only extensions:

# Copy farm configs from the NAS backup (e.g. <code>/volume2/Backups/wiki-migration-*</code> or <code>/volume2/web_packages/mediawiki/</code>).
# Merge any <code>wfLoadExtension(...)</code> lines into the matching VPS <code>LocalSettings.php</code>.
# Run <code>maintenance/run.php update --quick</code> in the affected container.

<code>$wgEnableUploads</code> is enabled so existing files under <code>wiki/images/</code> and <code>werbs-wiki/images/</code> remain usable.

== Scripts (<code>/var/www/wiki.jb/scripts/</code>) ==

{| class="wikitable"
|-
| Script || Purpose
|-
| <code>backup-wikis.sh</code> || Dump both DBs and image trees to <code>backups/YYYY-MM-DD/</code>
|-
| <code>fix-logos.sh</code> || Set <code>$wgLogos</code> paths after image changes
|-
| <code>init-db-users.sh</code> || Create/grant <code>wikiuser</code> in MariaDB
|-
| <code>install-wikis.sh</code> || Fresh MediaWiki install (empty DB only)
|}

== First-time install (empty databases) ==

Only needed on a fresh stack without imported content:

<pre class="lang-bash">
cd /var/www/wiki.jb
cp .env.example .env # set passwords
docker compose up -d
bash scripts/init-db-users.sh
bash scripts/install-wikis.sh
</pre>

Admin credentials from <code>.env</code>: <code>WIKI_ADMIN_USER</code> / <code>WIKI_ADMIN_PASSWORD</code> (installer account; production wiki admin is the imported '''Josh''' sysop account).

[[Category:Documentation]]
[[Category:Documentation/Wiki]]

Documentation:Wiki Deployment

2026-05-16T14:07:27Z

Josh: Updated documentation from markdown files

Production wikis run on this VPS under <code>/var/www/wiki.jb/</code>.

== Stack ==

{| class="wikitable"
|-
| Service || Container || Public URL || Upstream
|-
| Main wiki || <code>wiki-mediawiki</code> || https://wiki.jb-vpn.uk || <code>127.0.0.1:8010</code>
|-
| Werbs wiki || <code>wiki-werbs-mediawiki</code> || https://werbs-wiki.jb-vpn.uk || <code>127.0.0.1:8011</code>
|-
| Database || <code>wiki-mariadb</code> || (internal) || <code>127.0.0.1:3307</code>
|}

* '''MediaWiki version''': 1.44 (Docker image <code>mediawiki:1.44</code>)

* '''Edge proxy''': Caddy (<code>/etc/caddy/Caddyfile</code>) terminates HTTPS and proxies to the containers

* '''Config on host''': <code>wiki/LocalSettings.php</code>, <code>werbs-wiki/LocalSettings.php</code> (mounted read-only; group <code>www-data</code> must be able to read)

* '''Uploads''': <code>wiki/images/</code>, <code>werbs-wiki/images/</code>

== Daily operations ==

<pre class="lang-bash">
cd /var/www/wiki.jb
docker compose ps
docker compose logs -f wiki
docker compose restart wiki werbs-wiki
</pre>

Upload documentation from the VPS:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload -y
python3 /root/wiki_manager.py --update-main-page -y
</pre>

Optional uploads without public HTTPS round-trip:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload -y --wiki-url http://127.0.0.1:8010
</pre>

== Email ==

Outbound mail uses Fastmail SMTP (configured in each <code>LocalSettings.php</code>: <code>$wgSMTP</code>, <code>$wgPasswordSender</code>, <code>$wgEmergencyContact</code>). After editing settings on the host, ensure permissions remain <code>640</code> and group <code>www-data</code>.

== Backups ==

<pre class="lang-bash">
cd /var/www/wiki.jb
source .env
mkdir -p backups
docker compose exec -T mariadb mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" mediawiki \
> backups/mediawiki-$(date +%F).sql
docker compose exec -T mariadb mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" mediawiki_werbs \
> backups/mediawiki_werbs-$(date +%F).sql
tar -czf backups/wiki-images-$(date +%F).tar.gz wiki/images werbs-wiki/images
</pre>

== Maintenance ==

<pre class="lang-bash">
cd /var/www/wiki.jb
source .env
docker compose exec -T wiki php maintenance/run.php update --quick --conf /var/www/html/LocalSettings.php
docker compose exec -T werbs-wiki php maintenance/run.php update --quick --conf /var/www/html/LocalSettings.php
</pre>

Logos after image restores: <code>bash scripts/fix-logos.sh</code>

== Scripts (<code>/var/www/wiki.jb/scripts/</code>) ==

{| class="wikitable"
|-
| Script || Purpose
|-
| <code>fix-logos.sh</code> || Set <code>$wgLogos</code> paths after image changes
|-
| <code>init-db-users.sh</code> || Create/grant <code>wikiuser</code> in MariaDB
|-
| <code>install-wikis.sh</code> || Fresh MediaWiki install (empty DB only)
|}

== First-time install (empty databases) ==

Only needed on a fresh stack without imported content:

<pre class="lang-bash">
cd /var/www/wiki.jb
cp .env.example .env # set passwords
docker compose up -d
bash scripts/init-db-users.sh
bash scripts/install-wikis.sh
</pre>

Admin credentials from <code>.env</code>: <code>WIKI_ADMIN_USER</code> / <code>WIKI_ADMIN_PASSWORD</code> (installer account; production wiki admin is the imported '''Josh''' sysop account).

[[Category:Documentation]]
[[Category:Documentation/Wiki]]

Main Page

2026-05-16T14:04:36Z

Josh: Updated Main Page with comprehensive documentation links

== Welcome to the jb-vpn.uk Wiki ==

This wiki contains documentation for the jb-vpn.uk infrastructure: reverse proxy (Caddy), VPS-hosted services (WebApp, MediaWiki), and Synology NAS services reached via OpenVPN (DSM, Plex).

== Documentation ==

The following documentation is available:

=== Cursor SSH ===

* [[Cursor SSH:Quick Reference|Quick Reference]]
* [[Cursor SSH:Setup|Setup]]

=== OpenVPN ===

* [[OpenVPN:Certificate Management|Certificate Management]]
* [[OpenVPN:Client Configuration|Client Configuration]]
* [[OpenVPN:Integration|Integration]]
* [[OpenVPN:Raspberry Pi Auto Connect|Raspberry Pi Auto Connect]]
* [[OpenVPN:Server Configuration|Server Configuration]]
* [[OpenVPN:User Management|User Management]]

=== SSH Port Forwarding ===

* [[SSH Port Forwarding:Best Practices|Best Practices]]
* [[SSH Port Forwarding:Configuration|Configuration]]
* [[SSH Port Forwarding:Management|Management]]
* [[SSH Port Forwarding:Overview|Overview]]
* [[SSH Port Forwarding:Quickstart|Quickstart]]

=== Services ===

* [[Services:Current Services|Current Services]]

==== Adding Services ====
* [[Services:Best Practices|Best Practices]]
* [[Services:Configuration Options|Configuration Options]]
* [[Services:Prerequisites|Prerequisites]]
* [[Services:Service Examples|Service Examples]]
* [[Services:Step By Step|Step By Step]]

=== System ===

* [[System:Components|Components]]
* [[System:DNS Requirements|DNS Requirements]]
* [[System:Network Architecture|Network Architecture]]
* [[System:Security|Security]]
* [[System:Service Management|Service Management]]

=== Troubleshooting ===

* [[Troubleshooting:Nginx Troubleshooting|Nginx Troubleshooting]]
* [[Troubleshooting:Openvpn Troubleshooting|Openvpn Troubleshooting]]
* [[Troubleshooting:Port Forwarding Troubleshooting|Port Forwarding Troubleshooting]]
* [[Troubleshooting:Service Troubleshooting|Service Troubleshooting]]

=== Webapp ===

* [[Webapp:Deployment|Deployment]]

=== Wiki Management ===

* [[Wiki Management:Upload Instructions|Upload Instructions]]

== Quick Links ==

=== Services ===
* [[Main Page|Wiki Home]] - This page
* [https://dsm.jb-vpn.uk Synology DSM] - Synology management interface
* [https://plex.jb-vpn.uk Plex Media Server] - Media server
* [https://vps.jb-vpn.uk VPS Default] - VPS web directory

== System Information ==

* '''VPS IP''': 87.106.61.62
* '''VPN Network''': 10.8.0.0/24
* '''Synology NAS''': 10.8.0.2 (via VPN)
* '''Edge proxy''': Caddy (ports 80/443)
* '''SSL''': Let's Encrypt (automatic via Caddy)

== Quick Reference Commands ==

<pre class="lang-bash">
# Caddy
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
journalctl -u caddy -n 50

# Wiki stack
cd /var/www/wiki.jb && docker compose ps

# Test public wiki
curl -I https://wiki.jb-vpn.uk
</pre>

Wiki Management:Upload Instructions

2026-05-16T14:04:36Z

Josh: Updated documentation from markdown files

This guide explains how to upload the documentation files to your MediaWiki instance.

== Option 1: Automated Upload (Recommended) ==

Use the unified wiki manager script to automatically upload all documentation files.

=== Prerequisites ===

The script requires <code>mwclient</code> library, which should already be installed:
<pre class="lang-bash">
pip3 install --break-system-packages mwclient
</pre>

=== Usage ===

'''First time setup''' - Store credentials:
<pre class="lang-bash">
python3 /root/wiki_manager.py --store-credentials
</pre>

'''Upload all documentation files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload
</pre>

'''Update the Main Page with documentation links:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

'''Do both at once:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --update-main-page
</pre>

'''Check sync status:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --status
</pre>

'''Sync changes from wiki to local files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --sync
</pre>

'''Delete orphaned wiki pages''' (pages that no longer have corresponding local files):
<pre class="lang-bash">
== Preview what would be deleted (dry run - recommended first) ==
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== Actually delete orphaned pages (with confirmation) ==
python3 /root/wiki_manager.py --delete-orphaned

== Delete orphaned pages without confirmation (non-interactive) ==
python3 /root/wiki_manager.py --delete-orphaned -y
</pre>

'''Upload new docs and delete old orphaned pages in one go:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --delete-orphaned -y
</pre>

=== Managing Orphaned Pages ===

When you restructure documentation (e.g., breaking large files into smaller sub-pages), old wiki pages may become "orphaned" - they exist on the wiki but no longer have corresponding local files.

The <code>--delete-orphaned</code> feature helps you clean up these old pages:

==== '''Finds orphaned pages''': Automatically searches for all <code>Documentation:</code> pages on the wiki and compares them with your local files ====
== '''Shows what would be deleted''': Lists all orphaned pages with their content length ==
== '''Safety features''': ==
* Use <code>--dry-run</code> first to preview what would be deleted

* Requires confirmation (or use <code>-y</code> flag for non-interactive mode)

* Shows detailed information about each page before deletion

'''Example workflow after restructuring documentation:'''

<pre class="lang-bash">
== 1. First, preview what would be deleted ==
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== 2. If the list looks correct, actually delete them ==
python3 /root/wiki_manager.py --delete-orphaned -y

== 3. Upload the new restructured documentation ==
python3 /root/wiki_manager.py --upload --update-main-page
</pre>

'''Note''': The script only deletes pages in the <code>Documentation:</code> namespace that don't have corresponding local files. It will never delete pages that still have local files, ensuring your active documentation is always preserved.

=== Customizing Upload Comments ===

By default, the script uses the comment "Uploaded documentation from markdown files" for all uploads. You can customize this behavior in two ways:

==== Option 1: Custom Comment ====

Use the <code>--comment</code> flag to specify a custom comment that will be used for all uploads:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --comment "Updated documentation for v2.0"
</pre>

This is useful when you want to provide a specific message for a batch of uploads, such as:
* Version updates: <code>--comment "Documentation update for version 2.1"</code>

* Feature additions: <code>--comment "Added new SSH port forwarding documentation"</code>

* Bug fixes: <code>--comment "Fixed formatting issues in configuration guides"</code>

==== Option 2: Auto-Generated Comments ====

Use the <code>--auto-comment</code> flag to automatically generate meaningful comments based on the content of each file:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --auto-comment
</pre>

The auto-comment feature analyzes each file to generate contextual comments such as:
* <code>"Added configuration guide: SSH Port Forwarding (configuration)"</code>

* <code>"Major update - troubleshooting guide: Port Forwarding Troubleshooting (3 sections) (troubleshooting)"</code>

* <code>"Content added - overview: System Overview (getting started)"</code>

The auto-comment generator:
* Detects document type (troubleshooting guide, configuration guide, overview, etc.)

* Identifies whether it's a new page or an update

* Compares with existing wiki content to detect changes (major update, content added, minor update)

* Extracts the document title from markdown headers

* Counts sections to provide context

* Categorizes based on file path

'''Note''': The <code>--comment</code> flag takes precedence over <code>--auto-comment</code>. If both are specified, the custom comment will be used.

'''Examples:'''

<pre class="lang-bash">
== Upload with auto-generated comments ==
python3 /root/wiki_manager.py --upload --auto-comment

== Upload with custom comment and update main page ==
python3 /root/wiki_manager.py --upload --update-main-page --comment "Major documentation update"

== Upload with custom comment in non-interactive mode ==
python3 /root/wiki_manager.py --upload --comment "Quick fix" -y
</pre>

=== What the Script Does ===

The unified wiki manager script:
==== Automatically discovers all documentation files in the <code>/root/documentation/</code> directory ====
== Converts markdown files to MediaWiki wikitext format ==
== Maps files to wiki pages based on folder structure: ==
* <code>getting-started/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>getting-started/system-overview/index.md</code> → <code>Documentation:Index</code>)

* <code>configuration/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>configuration/adding-services/step-by-step.md</code> → <code>Documentation:Step By Step</code>)

* <code>troubleshooting/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>troubleshooting/port-forwarding-troubleshooting.md</code> → <code>Documentation:Port Forwarding Troubleshooting</code>)

* <code>wiki-management/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>wiki-management/upload-instructions.md</code> → <code>Documentation:Upload Instructions</code>)

== Uploads all documentation pages to the wiki ==
== Can update the Main Page with links to all documentation ==
== Can identify and delete orphaned wiki pages (pages without corresponding local files) ==

=== Customizing Wiki URL ===

The script automatically detects the wiki URL. To specify a custom URL, edit the script or use environment variables.

----

== Option 2: Manual Upload ==

If you prefer to upload manually or the script doesn't work:

=== Step 1: Access the Wiki ===

==== Navigate to your wiki: [https://wiki.jb-vpn.uk/index.php?title=Main_Page https://wiki.jb-vpn.uk/index.php?title=Main_Page] ====
== Log in with your MediaWiki account ==

=== Step 2: Create the Documentation Namespace ===

==== Go to: [https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage] ====
== Create a page named <code>Documentation:Index</code> ==
== Or navigate directly: [https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit] ==

=== Step 3: Convert and Paste Content ===

For each documentation file:

==== '''Read the markdown file''': ====
<pre class="lang-bash">
cat /root/documentation/index.md
</pre>

== '''Manually convert key elements''': ==
* <code># Header</code> → <code>= Header =</code>

* <code>## Header</code> → <code>== Header ==</code>

* <code>### Header</code> → <code>=== Header ===</code>

* Inline code: `<code> </code>code<code> </code><code> → </code><code>code</code><code>

* </code>'''bold'''<code> → </code>'''bold'''<code>

* </code>*italic*<code> → </code>*italic*<code>

* Code blocks: Wrap with </code><syntaxhighlight lang="bash"><code> and </code></syntaxhighlight><code>

== '''Create the pages''': ==
* </code>Documentation:Index<code> (from </code>documentation/index.md<code>)

* </code>Documentation:System_Overview<code> (from </code>documentation/getting-started/system-overview.md<code>)

* </code>Documentation:Adding_Services<code> (from </code>documentation/configuration/adding-services.md<code>)

* </code>Documentation:Current_Services<code> (from </code>documentation/configuration/current-services.md<code>)

=== Step 4: Add Navigation ===

Create a navigation template or update the main page to link to:
* </code>[Documentation Index](index.md)<code>

* </code>[System Overview](System_Overview.md)<code>

* </code>[Adding Services](Adding_Services.md)<code>

* </code>[Current Services](Current_Services.md)<code>

----

== Option 3: Using MediaWiki API with curl ==

You can also use curl to upload via the MediaWiki API:

=== Step 1: Get Login Token ===

<pre class="lang-bash">
WIKI_URL="https://wiki.jb-vpn.uk"
USERNAME="your_username"
PASSWORD="your_password"

==== Get login token ====
LOGIN_TOKEN=$(curl -s "$WIKI_URL/api.php?action=query&meta=tokens&type=login&format=json" | grep -oP '(?<="logintoken":")[^"]''' # Login
LOGIN_RESULT=$(curl -s -c cookies.txt -b cookies.txt \
-d "action=login" \
-d "lgname=$USERNAME" \
-d "lgpassword=$PASSWORD" \
-d "lgtoken=$LOGIN_TOKEN" \
-d "format=json" \
"$WIKI_URL/api.php")

echo "Login: $LOGIN_RESULT"
</pre>

=== Step 2: Get Edit Token ===

<pre class="lang-bash">
EDIT_TOKEN=$(curl -s -b cookies.txt \
"$WIKI_URL/api.php?action=query&meta=tokens&format=json" | \
grep -oP '(?<="csrftoken":")[^"])''')
</pre>

=== Step 3: Upload Page ===

<pre class="lang-bash">
PAGE_NAME="Documentation:Index"
CONTENT=$(cat /root/documentation/index.md | sed 's/#/=/g') # Basic conversion

curl -s -b cookies.txt \
-d "action=edit" \
-d "title=$PAGE_NAME" \
-d "text=$CONTENT" \
-d "token=$EDIT_TOKEN" \
-d "format=json" \
"$WIKI_URL/api.php"
</pre>

'''Note''': This method requires manual markdown-to-wikitext conversion and is more complex.

----

== Troubleshooting ==

=== Script Authentication Issues ===

If login fails:
==== Verify your MediaWiki username and password ====
== Check that your account has edit permissions ==
== Ensure the wiki is accessible from the VPS ==

=== Connection Issues ===

If you can't connect:
<pre class="lang-bash">
==== Test connectivity ====
curl -I https://wiki.jb-vpn.uk

== Test API (public or local) ==
curl "https://wiki.jb-vpn.uk/api.php?action=query&meta=siteinfo&format=json"
curl "http://127.0.0.1:8010/api.php?action=query&meta=siteinfo&format=json"
</pre>

=== Permission Issues ===

Ensure your MediaWiki account has:
* </code>edit<code> permission

* </code>createpage` permission (if pages don't exist)

----

=== Updating the Main Page ===

To update the Main Page with links to all documentation:

<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

This will add a comprehensive list of all documentation pages to the Main Page.

=== Complete Workflow Example ===

Here's a complete example workflow for restructuring documentation:

<pre class="lang-bash">
==== 1. Preview orphaned pages that would be deleted ====
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== 2. Delete orphaned pages (if the preview looks correct) ==
python3 /root/wiki_manager.py --delete-orphaned -y

== 3. Upload all new/updated documentation ==
python3 /root/wiki_manager.py --upload --auto-comment

== 4. Update the Main Page with new documentation structure ==
python3 /root/wiki_manager.py --update-main-page

== Or do steps 3 and 4 together: ==
python3 /root/wiki_manager.py --upload --update-main-page --auto-comment
</pre>

----

[[Category:Documentation]]
[[Category:Documentation/Wiki Management]]

Documentation:Wiki Deployment

2026-05-16T14:04:36Z

Josh: Uploaded documentation from markdown files

OpenVPN:Integration

2026-05-16T14:04:35Z

Josh: Updated documentation from markdown files

This document describes how the OpenVPN server integrates with the reverse proxy system.

== Integration Overview ==

The OpenVPN server is essential for the reverse proxy system:

=== '''Synology NAS connects''' via VPN (10.8.0.2) for DSM, Plex, and SSH ===
== '''Caddy reverse proxy''' forwards public hostnames to local VPS services or to 10.8.0.2 via VPN ==
== '''Services are accessible''' via HTTPS without exposing the NAS directly to the internet ==
== '''All traffic is encrypted''' through the VPN tunnel ==

== Network Flow ==

<pre>
Internet → VPS (87.106.61.62)
→ Caddy
→ (local) MediaWiki / WebApp on 127.0.0.1
→ (VPN) OpenVPN tun0 → 10.8.0.2 → DSM / Plex
</pre>

== How It Works ==

=== Client accesses a public subdomain (e.g., <code>dsm.jb-vpn.uk</code> or <code>wiki.jb-vpn.uk</code>) ===
== DNS resolves to VPS public IP (87.106.61.62) ==
== Caddy receives the request on port 443 (HTTPS) and terminates TLS ==
== For VPS-hosted services (wiki, WebApp), Caddy proxies to <code>127.0.0.1</code> ==
== For Synology services (DSM, Plex), Caddy proxies through the OpenVPN tunnel to <code>10.8.0.2</code> ==
== The backend responds; Caddy returns the response to the client ==

== Benefits ==

* '''No Direct Exposure''': Synology NAS is not directly accessible from the internet

* '''Encrypted Tunnel''': All traffic between VPS and NAS is encrypted via OpenVPN

* '''Secure Access''': Services are accessible via HTTPS while remaining isolated

* '''Centralized Management''': All services accessible through a single VPS

== Requirements ==

For the integration to work:

=== '''OpenVPN server must be running''' on the VPS ===
== '''Synology NAS must be connected''' to the VPN (10.8.0.2) for DSM/Plex/SSH forwards ==
== '''VPN tunnel must be active''' (tun0 interface up) for Synology-backed hostnames ==
== '''Caddy must be configured''' in <code>/etc/caddy/Caddyfile</code> ==

== Verification ==

Check that the integration is working:

<pre class="lang-bash">
=== Check VPN is running ===
systemctl status openvpn

== Check VPN interface ==
ip addr show tun0

== Check Synology is connected ==
ping -c 2 10.8.0.2

== Check wiki on VPS ==
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8010/

== Check DSM on Synology (via VPN) ==
curl -k -sI -m 5 https://10.8.0.2:5001/ | head -1
</pre>

== Related Documentation ==

* [System Overview](index.md) - Overall system architecture

* [Server Configuration](server-configuration.md) - OpenVPN server setup

* [Adding Services](index.md) - Configuring services

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]

Troubleshooting:Service Troubleshooting

2026-05-16T14:04:34Z

Josh: Updated documentation from markdown files

This guide covers troubleshooting for reverse proxy services.

== Common Issues ==

=== Issue: 502 Bad Gateway ===

'''Causes''':
* Backend not running (Docker on VPS or service on NAS)

* Caddy misconfigured or not reloaded after Caddyfile change

* Wrong port number

* Service not accessible via VPN

'''Solutions''':
<pre class="lang-bash">
==== Test from VPS to NAS ====
ping 10.8.0.2
curl http://10.8.0.2:PORT_NUMBER

== Check if service is listening ==
== (from Synology NAS or via SSH) ==
netstat -tlnp | grep PORT_NUMBER
</pre>

=== Issue: SSL Certificate Failed ===

'''Causes''':
* DNS not pointing to VPS

* Port 80 blocked

* Rate limiting from Let's Encrypt

'''Solutions''':
<pre class="lang-bash">
==== Check DNS ====
nslookup newservice.jb-vpn.uk

== Verify port 80 is open ==
curl -I http://newservice.jb-vpn.uk

== Check firewall ==
sudo iptables -L -n -v | grep 80
</pre>

=== Issue: Service Not Loading ===

'''Causes''':
* Wrong proxy_pass URL

* Missing headers

* Service requires specific path

'''Solutions''':
* Check Caddy: <code>journalctl -u caddy -n 50</code>

* Verify backend directly: <code>curl http://127.0.0.1:PORT</code> (VPS) or <code>curl http://10.8.0.2:PORT</code> (NAS via VPN)

* Test with different proxy_pass formats

=== Issue: Connection Timeout ===

'''Causes''':
* VPN tunnel down

* Service not accessible

* Firewall blocking

'''Solutions''':
<pre class="lang-bash">
==== Check VPN ====
ip addr show tun0
ping 10.8.0.2

== Check routing ==
ip route | grep 10.8.0.2

== Test connectivity ==
curl -v http://10.8.0.2:PORT_NUMBER
</pre>

== Diagnostic Commands ==

<pre class="lang-bash">
=== Check service status ===
systemctl status nginx

== Test nginx configuration ==
nginx -t

== View error logs ==
tail -f /var/log/nginx/error.log

== View access logs ==
tail -f /var/log/nginx/access.log

== Check SSL certificates ==
certbot certificates

== Test service directly ==
curl -I https://service.jb-vpn.uk
</pre>

== Related Documentation ==

* [Adding Services](index.md) - Service configuration

* [System Overview](index.md) - System architecture

[[Category:Documentation]]
[[Category:Documentation/Troubleshooting]]

Troubleshooting:Nginx Troubleshooting

2026-05-16T14:04:34Z

Josh: Updated documentation from markdown files

'''Note:''' Public HTTPS on this VPS is handled by '''Caddy''' (<code>/etc/caddy/Caddyfile</code>). Use [[System:Service Management]] and <code>journalctl -u caddy</code> for edge proxy issues.

This guide covers '''legacy host Nginx''' site files and the '''WebApp stack's internal Nginx''' container. Host Nginx is not the active edge proxy for <code>*.jb-vpn.uk</code> services.

== Configuration Errors ==

=== Syntax Errors ===

'''Symptoms''': <code>nginx -t</code> fails with syntax errors

'''Solutions''':
* Check for missing semicolons

* Verify bracket matching

* Check for typos in directive names

=== Duplicate Server Names ===

'''Symptoms''': Warning about duplicate server_name

'''Solutions''':
* Check all configuration files in <code>/etc/nginx/sites-enabled/</code>

* Remove duplicate server_name entries

* Ensure only one config per subdomain

== Service Issues ==

=== Nginx Won't Start ===

==== '''Check status''': ====
<pre class="lang-bash">
systemctl status nginx
</pre>

== '''Check logs''': ==
<pre class="lang-bash">
journalctl -u nginx -n 50
</pre>

== '''Test configuration''': ==
<pre class="lang-bash">
nginx -t
</pre>

=== Nginx Reload Fails ===

==== '''Test configuration first''': ====
<pre class="lang-bash">
nginx -t
</pre>

== '''Check for syntax errors''' in configuration files ==

== '''Verify file permissions''': ==
<pre class="lang-bash">
ls -la /etc/nginx/sites-enabled/
</pre>

== Log Analysis ==

=== Error Logs ===

<pre class="lang-bash">
==== View recent errors ====
tail -f /var/log/nginx/error.log

== Search for specific errors ==
grep "error" /var/log/nginx/error.log
</pre>

=== Access Logs ===

<pre class="lang-bash">
==== View recent access ====
tail -f /var/log/nginx/access.log

== Analyze traffic ==
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn
</pre>

== Common Configuration Issues ==

=== SSL Certificate Problems ===

* Verify certificate exists: <code>certbot certificates</code>

* Check certificate expiration: <code>openssl x509 -in /etc/letsencrypt/live/domain/cert.pem -noout -dates</code>

* Renew if needed: <code>certbot renew</code>

=== Proxy Issues ===

* Check proxy_pass URL is correct

* Verify target service is accessible

* Check proxy headers are set correctly

== Related Documentation ==

* [Adding Services](index.md) - Service configuration

* [Service Management](service-management.md) - Service management

[[Category:Documentation]]
[[Category:Documentation/Troubleshooting]]

Services:Service Examples

2026-05-16T14:04:34Z

Josh: Updated documentation from markdown files

Caddy snippets for <code>/etc/caddy/Caddyfile</code>. After editing, run <code>caddy validate</code> and <code>systemctl reload caddy</code>.

== MediaWiki (VPS Docker) ==

Already configured; reference:

<pre>
wiki.jb-vpn.uk {
reverse_proxy http://127.0.0.1:8010 {
header_up Host {host}
header_up X-Real-IP {remote}
header_up X-Forwarded-For {remote}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>

== Web application on VPS ==

<pre>
app.jb-vpn.uk {
reverse_proxy 127.0.0.1:8008
}
</pre>

== API on VPS with path prefix ==

<pre>
api.jb-vpn.uk {
reverse_proxy http://127.0.0.1:3000 {
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>

== Service on NAS (HTTP) ==

<pre>
internal.jb-vpn.uk {
reverse_proxy http://10.8.0.2:9000 {
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>

== Plex (NAS, custom headers) ==

See the <code>plex.jb-vpn.uk</code> block in <code>/etc/caddy/Caddyfile</code> for the full Plex header set.

== DSM (NAS, HTTPS upstream) ==

See the <code>dsm.jb-vpn.uk</code> block in <code>/etc/caddy/Caddyfile</code> (<code>tls_insecure_skip_verify</code> on the upstream transport).

== Static files on VPS ==

<pre>
vps.jb-vpn.uk {
root * /var/www/html
file_server
}
</pre>

== Related documentation ==

* [Step By Step Step-by-Step Process]

* [Configuration Options Configuration Options]

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Step By Step

2026-05-16T14:04:34Z

Josh: Updated documentation from markdown files

Follow these steps to expose a new service through the VPS reverse proxy (Caddy).

== Step 1: Add a Caddy site block ==

Edit <code>/etc/caddy/Caddyfile</code> and add a block for your hostname.

'''VPS-local service''' (Docker on <code>127.0.0.1</code>):

<pre>
newservice.jb-vpn.uk {
reverse_proxy http://127.0.0.1:PORT {
header_up Host {host}
header_up X-Real-IP {remote}
header_up X-Forwarded-For {remote}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>

'''NAS service''' (via OpenVPN at <code>10.8.0.2</code>):

<pre>
newservice.jb-vpn.uk {
reverse_proxy http://10.8.0.2:PORT {
header_up Host {host}
header_up X-Real-IP {remote}
header_up X-Forwarded-For {remote}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>

'''NAS HTTPS backend''' (e.g. DSM-style):

<pre>
newservice.jb-vpn.uk {
reverse_proxy https://10.8.0.2:PORT {
transport http {
tls_insecure_skip_verify
}
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>

Replace <code>PORT</code> with the internal port and ensure DNS points to the VPS.

== Step 2: Validate and reload ==

<pre class="lang-bash">
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
</pre>

== Step 3: Verify connectivity ==

<pre class="lang-bash">
nslookup newservice.jb-vpn.uk
curl -I https://newservice.jb-vpn.uk
</pre>

For NAS backends, confirm VPN first:

<pre class="lang-bash">
ping -c 2 10.8.0.2
curl -sI -m 5 http://10.8.0.2:PORT | head -1
</pre>

== Step 4: TLS ==

Caddy obtains and renews Let's Encrypt certificates automatically when:

* DNS for the hostname points to <code>87.106.61.62</code>

* Ports 80 and 443 are reachable on the VPS

Check logs if HTTPS fails on first request:

<pre class="lang-bash">
journalctl -u caddy -n 50
</pre>

== Step 5: Browser test ==

Open <code>https://newservice.jb-vpn.uk</code> and confirm the service loads with a valid certificate.

== Removing a service ==

# Remove the site block from <code>/etc/caddy/Caddyfile</code>
# <code>caddy validate --config /etc/caddy/Caddyfile</code>
# <code>systemctl reload caddy</code>

== Related documentation ==

* [Prerequisites Prerequisites]

* [Service Examples Service Examples]

* [Configuration Options Configuration Options]

* [[Services:Current Services]]

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Prerequisites

2026-05-16T14:04:34Z

Josh: Updated documentation from markdown files

Before adding a new public hostname, gather the following.

== Service information ==

* '''Hostname''' (e.g. <code>newservice.jb-vpn.uk</code>)

* '''Backend location''': VPS (<code>127.0.0.1:PORT</code>) or NAS via VPN (<code>10.8.0.2:PORT</code>)

* '''Protocol''': HTTP or HTTPS on the backend

== DNS ==

* '''A record''' pointing the hostname to <code>87.106.61.62</code>

* Propagation complete (verify with <code>dig</code> or <code>nslookup</code>)

<pre class="lang-bash">
dig newservice.jb-vpn.uk +short
</pre>

== Backend health ==

'''VPS service:'''

<pre class="lang-bash">
curl -sI http://127.0.0.1:PORT | head -1
</pre>

'''NAS service''' (requires active VPN):

<pre class="lang-bash">
ping -c 2 10.8.0.2
curl -sI -m 5 http://10.8.0.2:PORT | head -1
</pre>

'''Wiki example:'''

<pre class="lang-bash">
curl -sI http://127.0.0.1:8010 | head -1
curl -sI https://wiki.jb-vpn.uk | head -1
</pre>

== System requirements ==

* '''Caddy''' running on the VPS (<code>systemctl status caddy</code>)

* '''Ports 80/443''' reachable from the internet (for Let's Encrypt)

* '''OpenVPN''' up (<code>ip addr show tun0</code>) when the backend is on <code>10.8.0.2</code>

<pre class="lang-bash">
systemctl status caddy
ip addr show tun0
ping -c 2 10.8.0.2
</pre>

== Related documentation ==

* [Step By Step Step-by-Step Process]

* [[System:Network Architecture]]

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Best Practices

2026-05-16T14:04:34Z

Josh: Updated documentation from markdown files

Best practices when adding hostnames to the Caddy reverse proxy.

== General ==

* Validate the Caddyfile before reload: <code>caddy validate --config /etc/caddy/Caddyfile</code>

* Use clear subdomain names and document them in [[Services:Current Services]]

* Back up <code>/etc/caddy/Caddyfile</code> before changes

* Check <code>journalctl -u caddy</code> after adding a site

* Use HTTPS for all public services (Caddy handles certificates automatically)

* Test VPS backends with <code>curl</code> on <code>127.0.0.1</code> before testing the public URL

== Checklist ==

* [ ] DNS A record points to <code>87.106.61.62</code>

* [ ] Backend running and reachable from VPS (<code>127.0.0.1</code> or <code>10.8.0.2</code> via VPN)

* [ ] Site block added to <code>/etc/caddy/Caddyfile</code>

* [ ] <code>caddy validate</code> succeeds

* [ ] <code>systemctl reload caddy</code> completed

* [ ] <code>curl -I https://newservice.jb-vpn.uk</code> succeeds

* [ ] Browser test with valid certificate

* [ ] Entry added to [[Services:Current Services]]

== Security ==

* Prefer VPN-backed NAS services over exposing the NAS to the internet

* Restrict sensitive admin UIs where possible (e.g. phpMyAdmin basic auth in Caddyfile)

* Keep OpenVPN and VPS packages updated

== Related documentation ==

* [Step By Step Step-by-Step Process]

* [Prerequisites Prerequisites]

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Current Services

2026-05-16T14:04:33Z

Josh: Updated documentation from markdown files

This document provides a detailed inventory of all services currently configured on the reverse proxy system.

== Service Summary ==

{| class="wikitable"
|-
| Service || Subdomain || Internal Port || Protocol || Status || SSL
|-
| Wiki || wiki.jb-vpn.uk || 8010 || HTTP || Active || ✅
|-
| Werbs-Wiki || werbs-wiki.jb-vpn.uk || 8011 || HTTP || Active || ✅
|-
| Synology DSM || dsm.jb-vpn.uk || 5001 || HTTPS || Active || ✅
|-
| Plex Media Server || plex.jb-vpn.uk || 32400 || HTTP || Active || ✅
|-
| VPS Default || vps.jb-vpn.uk || - || - || Active || ✅
|}
== Service Details ==

=== 1. Wiki Service ===

'''Subdomain''': <code>wiki.jb-vpn.uk</code>

'''Public Access''': <code>https://wiki.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Host''': VPS (Docker)

* '''Target''': <code>127.0.0.1:8010</code> (container <code>wiki-mediawiki</code>)

* '''Stack''': <code>/var/www/wiki.jb/</code>

* '''Protocol''': HTTP

'''Reverse Proxy''':
* '''Caddy''': <code>/etc/caddy/Caddyfile</code> (<code>wiki.jb-vpn.uk</code> → <code>127.0.0.1:8010</code>)

'''SSL Certificate''':
* '''Provider''': Let's Encrypt (via Caddy)

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → wiki.jb-vpn.uk:443 (HTTPS)
→ Caddy (SSL termination)
→ 127.0.0.1:8010 (MediaWiki Docker on VPS)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* WebSocket support: ✅ Enabled

* Extended timeouts: ✅ 300 seconds

* Proxy headers: ✅ Full set configured

'''DNS Record''': <code>wiki.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://wiki.jb-vpn.uk
== Or access directly: https://wiki.jb-vpn.uk/index.php?title=Main_Page ==
</pre>

----

=== 2. Werbs-Wiki Service ===

'''Subdomain''': <code>werbs-wiki.jb-vpn.uk</code>

'''Public Access''': <code>https://werbs-wiki.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Host''': VPS (Docker)

* '''Target''': <code>127.0.0.1:8011</code> (container <code>wiki-werbs-mediawiki</code>)

* '''Stack''': <code>/var/www/wiki.jb/</code>

* '''Protocol''': HTTP

'''Reverse Proxy''':
* '''Caddy''': <code>/etc/caddy/Caddyfile</code> (<code>werbs-wiki.jb-vpn.uk</code> → <code>127.0.0.1:8011</code>)

'''SSL Certificate''':
* '''Provider''': Let's Encrypt (via Caddy)

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → werbs-wiki.jb-vpn.uk:443 (HTTPS)
→ Caddy (SSL termination)
→ 127.0.0.1:8011 (MediaWiki Docker on VPS)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* WebSocket support: ✅ Enabled

* Extended timeouts: ✅ 300 seconds

* Proxy headers: ✅ Full set configured

'''DNS Record''': <code>werbs-wiki.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://werbs-wiki.jb-vpn.uk
</pre>

----

=== 3. Synology DSM ===

'''Subdomain''': <code>dsm.jb-vpn.uk</code>

'''Public Access''': <code>https://dsm.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Target IP''': <code>10.8.0.2</code> (Synology NAS via VPN)

* '''Target Port''': <code>5001</code>

* '''Protocol''': HTTPS

'''Reverse Proxy''':
* '''Caddy''': <code>/etc/caddy/Caddyfile</code> (<code>dsm.jb-vpn.uk</code> → <code>https://10.8.0.2:5001</code>)

'''SSL Certificate''':
* '''Provider''': Let's Encrypt (via Caddy)

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → dsm.jb-vpn.uk:443 (HTTPS)
→ Caddy (SSL termination)
→ 10.8.0.2:5001 (HTTPS on NAS via VPN)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* WebSocket support: ✅ Enabled (for DSM WebSocket features)

* Internal HTTPS: ✅ Passes through to Synology HTTPS

'''DNS Record''': <code>dsm.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://dsm.jb-vpn.uk
</pre>

----

=== 4. Plex Media Server ===

'''Subdomain''': <code>plex.jb-vpn.uk</code>

'''Public Access''': <code>https://plex.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Target IP''': <code>10.8.0.2</code> (Synology NAS via VPN)

* '''Target Port''': <code>32400</code>

* '''Protocol''': HTTP

'''Reverse Proxy''':
* '''Caddy''': <code>/etc/caddy/Caddyfile</code> (<code>plex.jb-vpn.uk</code> → <code>http://10.8.0.2:32400</code>)

'''SSL Certificate''':
* '''Provider''': Let's Encrypt (via Caddy)

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → plex.jb-vpn.uk:443 (HTTPS)
→ Caddy (SSL termination)
→ 10.8.0.2:32400 (HTTP on NAS via VPN)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* Plex-specific headers: ✅ Configured

* X-Plex-Client-Identifier

* X-Plex-Device

* X-Plex-Product

* X-Plex-Version

* X-Plex-Platform

* X-Plex-Platform-Version

* X-Plex-Device-Name

* X-Plex-Provides

* X-Plex-Token

'''DNS Record''': <code>plex.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://plex.jb-vpn.uk
</pre>

----

=== 5. VPS Default Web Directory ===

'''Subdomain''': <code>vps.jb-vpn.uk</code>

'''Public Access''': <code>https://vps.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Type''': Static files

* '''Web Root''': <code>/var/www/html</code>

* '''Protocol''': Direct file serving

'''Reverse Proxy''':
* '''Caddy''': <code>/etc/caddy/Caddyfile</code> (<code>vps.jb-vpn.uk</code> — <code>file_server</code> for <code>/var/www/html</code>)

'''SSL Certificate''':
* '''Provider''': Let's Encrypt (via Caddy)

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → vps.jb-vpn.uk:443 (HTTPS)
→ Caddy (SSL termination + file_server)
→ /var/www/html
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* Static file serving: ✅ Enabled

* Index files: <code>index.html</code>, <code>index.htm</code>, <code>index.nginx-debian.html</code>

'''DNS Record''': <code>vps.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://vps.jb-vpn.uk
</pre>

----

== Additional Services (Non-Web) ==

=== SSH Port Forwarding ===

SSH port forwarding is managed through a centralized configuration system. See [SSH Port Forwarding Management](index.md) for complete documentation.

'''Current Forwards''':
* '''Synology NAS''': Port <code>22222</code> → <code>10.8.0.2:22</code>

* Access: <code>ssh -p 22222 user@87.106.61.62</code>

'''Management''':
<pre class="lang-bash">
== List all SSH port forwards ==
sudo ssh-forward list

== Add a new device ==
sudo ssh-forward add <name> <external_port> <vpn_ip> [ssh_port]

== Remove a device ==
sudo ssh-forward remove <name>
</pre>

'''Configuration File''': <code>/etc/ssh-port-forwards.conf</code>

'''Note''': This is a direct port forward via iptables, not handled by Caddy.

----

== Service Status Monitoring ==

=== Check All Services ===

<pre class="lang-bash">
==== Test all HTTPS services ====
for domain in wiki.jb-vpn.uk werbs-wiki.jb-vpn.uk dsm.jb-vpn.uk plex.jb-vpn.uk vps.jb-vpn.uk; do
echo "Testing $domain..."
curl -I -s https://$domain | head -1
done
</pre>

=== Check Caddy ===

<pre class="lang-bash">
systemctl status caddy
caddy validate --config /etc/caddy/Caddyfile
</pre>

----

== Service Dependencies ==

=== Required for All Services ===

==== '''OpenVPN Tunnel''': Must be active (tun0 interface up) for Synology-backed services ====
== '''Synology NAS''': Must be connected to VPN (10.8.0.2 reachable) for DSM/Plex ==
== '''Caddy''': Must be running on the VPS (ports 80/443) ==
== '''DNS Records''': Must point to VPS IP (87.106.61.62) ==

=== Service-Specific Requirements ===

* '''Wiki/Werbs-Wiki''': Docker stack at <code>/var/www/wiki.jb/</code> (<code>docker compose ps</code> healthy)

* '''DSM''': Synology DSM must be enabled

* '''Plex''': Plex Media Server must be running

* '''VPS Default''': No dependencies (local files only)

----

== Maintenance Schedule ==

=== Daily ===
* Check service availability (<code>curl -I</code> on key hostnames)

* Review Caddy logs if something fails (<code>journalctl -u caddy</code>)

=== Weekly ===
* <code>docker compose ps</code> for wiki and WebApp stacks

* Spot-check HTTPS on public hostnames

=== Monthly ===
* Backup <code>/etc/caddy/Caddyfile</code>

* Review and update documentation

=== Quarterly ===
* Verify TLS renewal via Caddy logs

* Review firewall rules

* Update system packages

----

== Service Statistics ==

'''Total Services''': 5 web services + 1 SSH port forward

'''Edge proxy''': Caddy (<code>/etc/caddy/Caddyfile</code>)

'''Configuration''': One Caddyfile for all public hostnames

'''Internal Ports Used (VPS)''': 8010, 8011, 8008, 8009, 8080 (phpMyAdmin)

'''Internal Ports Used (Synology via VPN)''': 5001, 32400, 22

----

[[Category:Documentation]]
[[Category:Documentation/Services]]

SSH Port Forwarding:Best Practices

2026-05-16T14:04:33Z

Josh: Updated documentation from markdown files

This document outlines best practices when adding new services to the reverse proxy system.

== General Best Practices ==

=== '''Always validate Caddy''' before reloading (<code>caddy validate</code>) when changing public hostnames ===
== '''Use descriptive subdomain names''' that indicate the service ==
== '''Document your services''' in [Current Services](current-services.md) ==
== '''Backup configurations''' before making changes ==
== '''Monitor logs''' after adding new services ==
== '''Use HTTPS''' for all public-facing services ==
== '''Test thoroughly''' before marking service as complete ==

== Checklist ==

Use this checklist when adding a new service:

* [ ] DNS A record created and propagated

* [ ] Service running on Synology NAS

* [ ] Service accessible from VPN network

* [ ] Nginx configuration file created

* [ ] Site enabled (symlink created)

* [ ] Nginx configuration tested (<code>nginx -t</code>)

* [ ] Nginx reloaded

* [ ] HTTP access verified

* [ ] SSL certificate obtained

* [ ] HTTPS access verified

* [ ] Browser testing completed

* [ ] Service documented in [Current Services](current-services.md)

== Security Considerations ==

* Always use HTTPS for public-facing services

* Keep SSL certificates up to date (automatic renewal via Certbot)

* Use strong authentication for services that require it

* Monitor access logs for unusual activity

== Related Documentation ==

* [Step-by-Step Process](step-by-step.md) - Setup process

* [[Documentation:Index|Troubleshooting]] - Common issues

[[Category:Documentation]]
[[Category:Documentation/SSH Port Forwarding]]

System:Network Architecture

2026-05-16T14:04:33Z

Josh: Updated documentation from markdown files

This document describes the network architecture of the jb-vpn.uk infrastructure.

== Network topology ==

<pre>
Internet → VPS (87.106.61.62) → Caddy (443)
├→ 127.0.0.1 — Docker (WebApp, MediaWiki, phpMyAdmin)
└→ OpenVPN (tun0) → NAS (10.8.0.2) — DSM, Plex, SSH
</pre>

== Network components ==

* '''VPS public IP''': <code>87.106.61.62</code>

* '''VPN network''': <code>10.8.0.0/24</code>

* '''VPN interface''': <code>tun0</code> (<code>10.8.0.1</code> on VPS)

* '''NAS VPN IP''': <code>10.8.0.2</code>

* '''Edge proxy''': Caddy (ports 80/443)

* '''TLS''': Let's Encrypt (automatic via Caddy)

== Traffic flow ==

# '''Client request''' — user opens a hostname (e.g. <code>wiki.jb-vpn.uk</code>)
# '''DNS''' — record points to <code>87.106.61.62</code>
# '''Caddy''' — receives HTTPS on port 443, terminates TLS
# '''Routing''' — Caddy proxies to a local upstream or through <code>tun0</code> to <code>10.8.0.2</code>
# '''Response''' — backend → Caddy → client

Example (main wiki):

<pre>
Browser → wiki.jb-vpn.uk:443 → Caddy → 127.0.0.1:8010 (wiki-mediawiki)
</pre>

Example (DSM):

<pre>
Browser → dsm.jb-vpn.uk:443 → Caddy → https://10.8.0.2:5001
</pre>

== Network diagram ==

<pre>
┌─────────────┐
│ Client │
└──────┬──────┘
│ HTTPS (443)
▼
┌─────────────────────────────────────┐
│ VPS (87.106.61.62) │
│ ┌───────────────────────────────┐ │
│ │ Caddy (TLS + routing) │ │
│ └───────────┬───────────────────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ ▼ ▼ │
│ 127.0.0.1 tun0 → 10.8.0.2 │
│ Docker stacks NAS services │
│ - 8010/8011 Wiki - 5001 DSM │
│ - 8008/8009 App - 32400 Plex │
│ - 8080 phpMyAdmin │
└─────────────────────────────────────┘
</pre>

== Ports ==

=== Public (VPS) ===

{| class="wikitable"
|-
| Port || Purpose
|-
| 80 || HTTP → HTTPS redirect (Caddy)
|-
| 443 || HTTPS (Caddy)
|-
| 22 || SSH (VPS admin)
|-
| 1194/udp || OpenVPN server
|-
| 22222 || SSH forward to NAS (iptables)
|}

=== Local (VPS <code>127.0.0.1</code>) ===

{| class="wikitable"
|-
| Port || Service
|-
| 8010 || Main MediaWiki
|-
| 8011 || Werbs MediaWiki
|-
| 3307 || Wiki MariaDB
|-
| 8008 || WebApp production
|-
| 8009 || WebApp beta
|-
| 8080 || phpMyAdmin
|}

=== NAS (via VPN <code>10.8.0.2</code>) ===

{| class="wikitable"
|-
| Port || Service
|-
| 5001 || DSM (HTTPS)
|-
| 32400 || Plex
|-
| 22 || SSH
|}

== Related documentation ==

* [Components Components] — component details

* [[Services:Current Services]] — hostname inventory

* [[OpenVPN:Integration|OpenVPN Integration]] — VPN and proxy interaction

[[Category:Documentation]]
[[Category:Documentation/System]]

System:Components

2026-05-16T14:04:32Z

Josh: Updated documentation from markdown files

This document describes the key components of the jb-vpn.uk infrastructure.

== Caddy (edge reverse proxy) ==

'''Purpose''': Entry point for public HTTPS traffic on the VPS. Terminates TLS, routes by hostname, and proxies to local Docker services or to the NAS over OpenVPN.

'''Configuration''': <code>/etc/caddy/Caddyfile</code>

'''Key features''':
* Automatic Let's Encrypt certificates and renewal

* HTTP → HTTPS redirects

* Host-based routing (<code>wiki.jb-vpn.uk</code>, <code>dsm.jb-vpn.uk</code>, etc.)

* Proxy headers (<code>Host</code>, <code>X-Real-IP</code>, <code>X-Forwarded-For</code>, <code>X-Forwarded-Proto</code>)

* WebSocket upgrade headers where needed

'''Management''':

<pre class="lang-bash">
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
systemctl status caddy
journalctl -u caddy -n 50
</pre>

== VPS-hosted services (Docker) ==

{| class="wikitable"
|-
| Service || Hostname || Local upstream
|-
| WebApp (prod) || <code>app.jb-vpn.uk</code> || <code>127.0.0.1:8008</code>
|-
| WebApp (beta) || <code>app-beta.josh.me.uk</code> || <code>127.0.0.1:8009</code>
|-
| phpMyAdmin || <code>app-db.josh.me.uk</code> || <code>127.0.0.1:8080</code>
|-
| Main wiki || <code>wiki.jb-vpn.uk</code> || <code>127.0.0.1:8010</code>
|-
| Werbs wiki || <code>werbs-wiki.jb-vpn.uk</code> || <code>127.0.0.1:8011</code>
|-
| Static site || <code>vps.jb-vpn.uk</code> || <code>/var/www/html</code>
|}

MediaWiki stack path: <code>/var/www/wiki.jb/</code>

== OpenVPN tunnel ==

'''Purpose''': Encrypted access from the VPS to the NAS for DSM, Plex, and SSH port forwarding.

'''Network''':
* VPN server (VPS): <code>10.8.0.1</code> on <code>tun0</code>

* NAS client: <code>10.8.0.2</code>

* Subnet: <code>10.8.0.0/24</code>

Caddy reaches NAS services at <code>10.8.0.2</code> (e.g. DSM <code>:5001</code>, Plex <code>:32400</code>) only when the VPN tunnel is up.

== WebApp internal Nginx ==

The WebApp Docker stack uses its own '''Nginx''' container for PHP/Laravel routing on <code>127.0.0.1:8008</code> / <code>8009</code>. That is separate from the public edge proxy (Caddy).

== Firewall and routing ==

'''iptables''' on the VPS:
* NAT / port forwards (e.g. SSH <code>22222</code> → <code>10.8.0.2:22</code>)

* MASQUERADE for VPN clients

* FORWARD rules between <code>tun0</code> and internal targets

== Related documentation ==

* [Network Architecture Network Architecture] — topology and ports

* [Security Security] — security layers

* [[Services:Current Services]] — per-hostname inventory

[[Category:Documentation]]
[[Category:Documentation/System]]

System:Security

2026-05-16T14:04:32Z

Josh: Updated documentation from markdown files

This document describes the security architecture of the reverse proxy system.

== Defense in Depth ==

The system uses multiple layers of security:

=== '''Public Layer''': Caddy with SSL/TLS encryption (Let's Encrypt) ===
== '''VPN Layer''': Encrypted tunnel between VPS and NAS ==
== '''Internal Layer''': Services only accessible via VPN ==
== '''Certificate Security''': Automatic renewal prevents expired certificates ==

== Security Benefits ==

* '''No Direct Exposure''': Synology NAS is not directly accessible from the internet

* '''Encrypted Traffic''': All public traffic uses HTTPS

* '''Isolated Network''': Internal services communicate over VPN

* '''Certificate Management''': Automatic SSL certificate renewal

== Security Components ==

=== SSL/TLS Encryption ===

* All public-facing traffic uses HTTPS

* Let's Encrypt certificates automatically renew

* HTTP traffic is redirected to HTTPS

=== VPN Encryption ===

* OpenVPN provides encrypted tunnel between VPS and NAS

* All internal traffic is encrypted through VPN

* Certificate-based authentication for VPN clients

=== Network Isolation ===

* Internal services only accessible via VPN

* No direct internet exposure of Synology NAS

* Firewall rules control traffic flow

== Related Documentation ==

* [Network Architecture](network-architecture.md) - Network topology

* [Key Components](components.md) - Component details

* [OpenVPN Server](index.md) - VPN security configuration

[[Category:Documentation]]
[[Category:Documentation/System]]

System:Service Management

2026-05-16T14:04:32Z

Josh: Updated documentation from markdown files

This document describes how to manage edge proxy and related services on the VPS.

== Caddy (public reverse proxy) ==

=== Status ===

<pre class="lang-bash">
systemctl status caddy
</pre>

=== Validate configuration ===

<pre class="lang-bash">
caddy validate --config /etc/caddy/Caddyfile
</pre>

=== Apply changes ===

<pre class="lang-bash">
systemctl reload caddy
</pre>

=== Logs ===

<pre class="lang-bash">
journalctl -u caddy -f
journalctl -u caddy -n 100 --no-pager
</pre>

=== Backup Caddyfile ===

<pre class="lang-bash">
cp -a /etc/caddy/Caddyfile /root/backups/caddy/Caddyfile.$(date +%F)
</pre>

== MediaWiki stack ==

<pre class="lang-bash">
cd /var/www/wiki.jb
docker compose ps
docker compose logs -f wiki
docker compose restart wiki werbs-wiki
</pre>

See [[Webapp:Deployment|Documentation:Wiki Deployment]].

== WebApp stack ==

See [[Webapp:Deployment|Webapp:Deployment]].

== OpenVPN ==

<pre class="lang-bash">
systemctl status openvpn-server@server
ip addr show tun0
</pre>

== Maintenance checklist ==

* Confirm Caddy is active and config validates after hostname changes

* Review <code>journalctl -u caddy</code> after incidents

* Keep Docker images updated for wiki and WebApp stacks

* Verify Let's Encrypt renewal (handled by Caddy; check logs if certificates near expiry)

== Related documentation ==

* [Network Architecture Network Architecture]

* [[Troubleshooting:Service Troubleshooting|Troubleshooting:Service Troubleshooting]]

* [[Troubleshooting:Nginx Troubleshooting|Troubleshooting:Nginx Troubleshooting]] — legacy reference only

[[Category:Documentation]]
[[Category:Documentation/System]]

Main Page

2026-02-05T22:46:53Z

Josh: Updated Main Page with comprehensive documentation links

== Welcome to the jb-vpn.uk Wiki ==

This wiki contains comprehensive documentation for the reverse proxy system that forwards traffic from public subdomains to services on a Synology NAS via OpenVPN.

== Documentation ==

The following documentation is available:

=== Cursor SSH ===

* [[Cursor SSH:Quick Reference|Quick Reference]]
* [[Cursor SSH:Setup|Setup]]

=== OpenVPN ===

* [[OpenVPN:Certificate Management|Certificate Management]]
* [[OpenVPN:Client Configuration|Client Configuration]]
* [[OpenVPN:Integration|Integration]]
* [[OpenVPN:Raspberry Pi Auto Connect|Raspberry Pi Auto Connect]]
* [[OpenVPN:Server Configuration|Server Configuration]]
* [[OpenVPN:User Management|User Management]]

=== SSH Port Forwarding ===

* [[SSH Port Forwarding:Best Practices|Best Practices]]
* [[SSH Port Forwarding:Configuration|Configuration]]
* [[SSH Port Forwarding:Management|Management]]
* [[SSH Port Forwarding:Overview|Overview]]
* [[SSH Port Forwarding:Quickstart|Quickstart]]

=== Services ===

* [[Services:Current Services|Current Services]]

==== Adding Services ====
* [[Services:Best Practices|Best Practices]]
* [[Services:Configuration Options|Configuration Options]]
* [[Services:Prerequisites|Prerequisites]]
* [[Services:Service Examples|Service Examples]]
* [[Services:Step By Step|Step By Step]]

=== System ===

* [[System:Components|Components]]
* [[System:DNS Requirements|DNS Requirements]]
* [[System:Network Architecture|Network Architecture]]
* [[System:Security|Security]]
* [[System:Service Management|Service Management]]

=== Troubleshooting ===

* [[Troubleshooting:Nginx Troubleshooting|Nginx Troubleshooting]]
* [[Troubleshooting:Openvpn Troubleshooting|Openvpn Troubleshooting]]
* [[Troubleshooting:Port Forwarding Troubleshooting|Port Forwarding Troubleshooting]]
* [[Troubleshooting:Service Troubleshooting|Service Troubleshooting]]

=== Webapp ===

* [[Webapp:Deployment|Deployment]]

=== Wiki Management ===

* [[Wiki Management:Upload Instructions|Upload Instructions]]

== Quick Links ==

=== Services ===
* [[Main Page|Wiki Home]] - This page
* [https://dsm.jb-vpn.uk Synology DSM] - Synology management interface
* [https://plex.jb-vpn.uk Plex Media Server] - Media server
* [https://vps.jb-vpn.uk VPS Default] - VPS web directory

== System Information ==

* '''VPS IP''': 87.106.61.62
* '''VPN Network''': 10.8.0.0/24
* '''Synology NAS''': 10.8.0.2 (via VPN)
* '''Web Server''': Nginx
* '''SSL''': Let's Encrypt (Certbot)

== Quick Reference Commands ==

<pre class="lang-bash">
# Test nginx configuration
nginx -t

# Reload nginx
systemctl reload nginx

# Check SSL certificates
certbot certificates

# View nginx logs
tail -f /var/log/nginx/error.log

# Test service
curl -I https://wiki.jb-vpn.uk
</pre>

Webapp:Deployment

2026-02-05T22:46:48Z

Josh: Uploaded documentation from markdown files

This guide describes how to deploy code changes and updates to the production Docker stack for WebApp (Laravel + Vue, served via Nginx). The same content is maintained in the WebApp repository as <code>DEPLOYMENT.md</code>; for current status and URLs see <code>DEPLOY-STATUS.md</code> in the repo.

== Overview ==

Production runs as a Docker Compose stack:

* '''app''' – PHP-FPM (Laravel), container name <code>webapp-php</code>

* '''nginx''' – reverse proxy, exposes app on <code>127.0.0.1:8008</code>

* '''db''' – MariaDB 11, data in volume <code>webapp-mysql-data</code>

App code is mounted from the host (<code>/root/WebApp</code>), so many updates only need pull + migrations + frontend build, without rebuilding images.

== Prerequisites ==

* SSH (or direct) access to the server where WebApp runs

* <code>docker</code> and <code>docker compose</code> available

* Repository at <code>/root/WebApp</code> (or adjust paths below)

* <code>.env</code> configured (database credentials, <code>APP_KEY</code>, <code>APP_URL</code>, etc.)

== Deployment Steps ==

=== 1. Go to the app directory ===

<pre class="lang-bash">
cd /root/WebApp
</pre>

=== 2. Pull latest code ===

<pre class="lang-bash">
git pull
</pre>

Resolve any merge conflicts before continuing.

=== 3. Rebuild Docker images (only when needed) ===

Rebuild '''only''' if you changed:

* <code>docker/Dockerfile</code>

* <code>docker-compose.yml</code> (service build context, Dockerfile path, or image name)

* Base PHP/extensions or system packages

<pre class="lang-bash">
docker compose build --no-cache app
docker compose up -d
</pre>

If you did '''not''' change the above, skip this step and keep the stack running.

=== 4. Install or update PHP dependencies ===

<pre class="lang-bash">
docker compose exec -T -u root app composer install --no-interaction
docker compose exec -T -u root app chown -R www:www /var/www/vendor /var/www/bootstrap/cache
</pre>

For major upgrades (e.g. Laravel version bump) you may use <code>composer update</code> instead of <code>composer install</code> after reviewing dependencies.

=== 5. Run database migrations ===

<pre class="lang-bash">
docker compose exec -T app php artisan migrate --force
</pre>

Use <code>--force</code> in production so the command does not prompt.

=== 6. Build frontend assets (Vite) ===

Required after any change to JS, CSS, or Vite config so <code>public/build/</code> is up to date:

<pre class="lang-bash">
docker run --rm -v "$(pwd):/app" -w /app node:20-bookworm-slim sh -c "npm ci && npm run build"
</pre>

Alternatively, build inside the app container and fix ownership:

<pre class="lang-bash">
docker compose exec -u root app sh -c "npm ci && npm run build && chown -R www:www /var/www/node_modules /var/www/public/build"
</pre>

=== 7. Clear application caches ===

<pre class="lang-bash">
docker compose exec -T app php artisan config:clear
docker compose exec -T app php artisan cache:clear
docker compose exec -T app php artisan view:clear
</pre>

Optional after config changes: <code>php artisan config:cache</code>.

=== 8. Restart app (and optionally Nginx) ===

If you only changed code or env (no image rebuild):

<pre class="lang-bash">
docker compose restart app
</pre>

If you changed Nginx config (<code>docker/nginx/conf.d/app.conf</code>):

<pre class="lang-bash">
docker compose restart nginx
</pre>

For a full stack restart:

<pre class="lang-bash">
docker compose up -d
</pre>

== Post-deploy verification ==

* '''Local HTTP check:'''

<code>curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8008/</code>
Expect <code>200</code>.

* '''Public URLs:'''

* https://app.josh.me.uk

* https://app.jb-vpn.uk

* '''Logs:'''

<code>docker compose logs -f app</code>
<code>docker compose logs -f nginx</code>

== When to run one-time setup again ==

The script <code>docker-setup.sh</code> is for '''initial''' setup (key:generate, migrate, db:seed, passport:install, storage:link). You do '''not''' need to run it on every deploy. Only re-run (or run its steps manually) if:

* You are deploying to a new environment, or

* You have added a step that is not yet in the normal deploy flow (e.g. a new artisan command that must run once).

== Summary: minimal deploy (code-only change) ==

For typical code-only updates (no Dockerfile/compose changes):

<pre class="lang-bash">
cd /root/WebApp
git pull
docker compose exec -T -u root app composer install --no-interaction
docker compose exec -T -u root app chown -R www:www /var/www/vendor /var/www/bootstrap/cache
docker compose exec -T app php artisan migrate --force
docker run --rm -v "$(pwd):/app" -w /app node:20-bookworm-slim sh -c "npm ci && npm run build"
docker compose exec -T app php artisan config:clear && docker compose exec -T app php artisan cache:clear
docker compose restart app
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8008/
</pre>

== Rollback ==

If a deploy causes issues:

# Revert code: <code>git checkout <previous-commit></code> (or <code>git revert</code> and then pull).
# Re-run the same steps (composer install, migrate if you need to reverse migrations separately, npm run build, clear caches, restart app).
# If you had run new migrations, consider <code>php artisan migrate:rollback</code> if appropriate, then redeploy the previous code.

Keep a note of the last known-good commit so you can return to it quickly.

[[Category:Documentation]]
[[Category:Documentation/Webapp]]

Wiki Management:Upload Instructions

2026-01-01T13:44:59Z

Josh: Major update - troubleshooting guide: Uploading Documentation to Wiki (61 sections) (wiki management)

This guide explains how to upload the documentation files to your MediaWiki instance.

== Option 1: Automated Upload (Recommended) ==

Use the unified wiki manager script to automatically upload all documentation files.

=== Prerequisites ===

The script requires <code>mwclient</code> library, which should already be installed:
<pre class="lang-bash">
pip3 install --break-system-packages mwclient
</pre>

=== Usage ===

'''First time setup''' - Store credentials:
<pre class="lang-bash">
python3 /root/wiki_manager.py --store-credentials
</pre>

'''Upload all documentation files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload
</pre>

'''Update the Main Page with documentation links:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

'''Do both at once:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --update-main-page
</pre>

'''Check sync status:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --status
</pre>

'''Sync changes from wiki to local files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --sync
</pre>

'''Delete orphaned wiki pages''' (pages that no longer have corresponding local files):
<pre class="lang-bash">
== Preview what would be deleted (dry run - recommended first) ==
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== Actually delete orphaned pages (with confirmation) ==
python3 /root/wiki_manager.py --delete-orphaned

== Delete orphaned pages without confirmation (non-interactive) ==
python3 /root/wiki_manager.py --delete-orphaned -y
</pre>

'''Upload new docs and delete old orphaned pages in one go:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --delete-orphaned -y
</pre>

=== Managing Orphaned Pages ===

When you restructure documentation (e.g., breaking large files into smaller sub-pages), old wiki pages may become "orphaned" - they exist on the wiki but no longer have corresponding local files.

The <code>--delete-orphaned</code> feature helps you clean up these old pages:

==== '''Finds orphaned pages''': Automatically searches for all <code>Documentation:</code> pages on the wiki and compares them with your local files ====
== '''Shows what would be deleted''': Lists all orphaned pages with their content length ==
== '''Safety features''': ==
* Use <code>--dry-run</code> first to preview what would be deleted

* Requires confirmation (or use <code>-y</code> flag for non-interactive mode)

* Shows detailed information about each page before deletion

'''Example workflow after restructuring documentation:'''

<pre class="lang-bash">
== 1. First, preview what would be deleted ==
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== 2. If the list looks correct, actually delete them ==
python3 /root/wiki_manager.py --delete-orphaned -y

== 3. Upload the new restructured documentation ==
python3 /root/wiki_manager.py --upload --update-main-page
</pre>

'''Note''': The script only deletes pages in the <code>Documentation:</code> namespace that don't have corresponding local files. It will never delete pages that still have local files, ensuring your active documentation is always preserved.

=== Customizing Upload Comments ===

By default, the script uses the comment "Uploaded documentation from markdown files" for all uploads. You can customize this behavior in two ways:

==== Option 1: Custom Comment ====

Use the <code>--comment</code> flag to specify a custom comment that will be used for all uploads:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --comment "Updated documentation for v2.0"
</pre>

This is useful when you want to provide a specific message for a batch of uploads, such as:
* Version updates: <code>--comment "Documentation update for version 2.1"</code>

* Feature additions: <code>--comment "Added new SSH port forwarding documentation"</code>

* Bug fixes: <code>--comment "Fixed formatting issues in configuration guides"</code>

==== Option 2: Auto-Generated Comments ====

Use the <code>--auto-comment</code> flag to automatically generate meaningful comments based on the content of each file:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --auto-comment
</pre>

The auto-comment feature analyzes each file to generate contextual comments such as:
* <code>"Added configuration guide: SSH Port Forwarding (configuration)"</code>

* <code>"Major update - troubleshooting guide: Port Forwarding Troubleshooting (3 sections) (troubleshooting)"</code>

* <code>"Content added - overview: System Overview (getting started)"</code>

The auto-comment generator:
* Detects document type (troubleshooting guide, configuration guide, overview, etc.)

* Identifies whether it's a new page or an update

* Compares with existing wiki content to detect changes (major update, content added, minor update)

* Extracts the document title from markdown headers

* Counts sections to provide context

* Categorizes based on file path

'''Note''': The <code>--comment</code> flag takes precedence over <code>--auto-comment</code>. If both are specified, the custom comment will be used.

'''Examples:'''

<pre class="lang-bash">
== Upload with auto-generated comments ==
python3 /root/wiki_manager.py --upload --auto-comment

== Upload with custom comment and update main page ==
python3 /root/wiki_manager.py --upload --update-main-page --comment "Major documentation update"

== Upload with custom comment in non-interactive mode ==
python3 /root/wiki_manager.py --upload --comment "Quick fix" -y
</pre>

=== What the Script Does ===

The unified wiki manager script:
==== Automatically discovers all documentation files in the <code>/root/documentation/</code> directory ====
== Converts markdown files to MediaWiki wikitext format ==
== Maps files to wiki pages based on folder structure: ==
* <code>getting-started/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>getting-started/system-overview/index.md</code> → <code>Documentation:Index</code>)

* <code>configuration/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>configuration/adding-services/step-by-step.md</code> → <code>Documentation:Step By Step</code>)

* <code>troubleshooting/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>troubleshooting/port-forwarding-troubleshooting.md</code> → <code>Documentation:Port Forwarding Troubleshooting</code>)

* <code>wiki-management/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>wiki-management/upload-instructions.md</code> → <code>Documentation:Upload Instructions</code>)

== Uploads all documentation pages to the wiki ==
== Can update the Main Page with links to all documentation ==
== Can identify and delete orphaned wiki pages (pages without corresponding local files) ==

=== Customizing Wiki URL ===

The script automatically detects the wiki URL. To specify a custom URL, edit the script or use environment variables.

----

== Option 2: Manual Upload ==

If you prefer to upload manually or the script doesn't work:

=== Step 1: Access the Wiki ===

==== Navigate to your wiki: [https://wiki.jb-vpn.uk/index.php?title=Main_Page https://wiki.jb-vpn.uk/index.php?title=Main_Page] ====
== Log in with your MediaWiki account ==

=== Step 2: Create the Documentation Namespace ===

==== Go to: [https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage] ====
== Create a page named <code>Documentation:Index</code> ==
== Or navigate directly: [https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit] ==

=== Step 3: Convert and Paste Content ===

For each documentation file:

==== '''Read the markdown file''': ====
<pre class="lang-bash">
cat /root/documentation/index.md
</pre>

== '''Manually convert key elements''': ==
* <code># Header</code> → <code>= Header =</code>

* <code>## Header</code> → <code>== Header ==</code>

* <code>### Header</code> → <code>=== Header ===</code>

* Inline code: `<code> </code>code<code> </code><code> → </code><code>code</code><code>

* </code>'''bold'''<code> → </code>'''bold'''<code>

* </code>*italic*<code> → </code>*italic*<code>

* Code blocks: Wrap with </code><syntaxhighlight lang="bash"><code> and </code></syntaxhighlight><code>

== '''Create the pages''': ==
* </code>Documentation:Index<code> (from </code>documentation/index.md<code>)

* </code>Documentation:System_Overview<code> (from </code>documentation/getting-started/system-overview.md<code>)

* </code>Documentation:Adding_Services<code> (from </code>documentation/configuration/adding-services.md<code>)

* </code>Documentation:Current_Services<code> (from </code>documentation/configuration/current-services.md<code>)

=== Step 4: Add Navigation ===

Create a navigation template or update the main page to link to:
* </code>[Documentation Index](index.md)<code>

* </code>[System Overview](System_Overview.md)<code>

* </code>[Adding Services](Adding_Services.md)<code>

* </code>[Current Services](Current_Services.md)<code>

----

== Option 3: Using MediaWiki API with curl ==

You can also use curl to upload via the MediaWiki API:

=== Step 1: Get Login Token ===

<pre class="lang-bash">
WIKI_URL="http://10.8.0.2:8080"
USERNAME="your_username"
PASSWORD="your_password"

==== Get login token ====
LOGIN_TOKEN=$(curl -s "$WIKI_URL/api.php?action=query&meta=tokens&type=login&format=json" | grep -oP '(?<="logintoken":")[^"]''' # Login
LOGIN_RESULT=$(curl -s -c cookies.txt -b cookies.txt \
-d "action=login" \
-d "lgname=$USERNAME" \
-d "lgpassword=$PASSWORD" \
-d "lgtoken=$LOGIN_TOKEN" \
-d "format=json" \
"$WIKI_URL/api.php")

echo "Login: $LOGIN_RESULT"
</pre>

=== Step 2: Get Edit Token ===

<pre class="lang-bash">
EDIT_TOKEN=$(curl -s -b cookies.txt \
"$WIKI_URL/api.php?action=query&meta=tokens&format=json" | \
grep -oP '(?<="csrftoken":")[^"])''')
</pre>

=== Step 3: Upload Page ===

<pre class="lang-bash">
PAGE_NAME="Documentation:Index"
CONTENT=$(cat /root/documentation/index.md | sed 's/#/=/g') # Basic conversion

curl -s -b cookies.txt \
-d "action=edit" \
-d "title=$PAGE_NAME" \
-d "text=$CONTENT" \
-d "token=$EDIT_TOKEN" \
-d "format=json" \
"$WIKI_URL/api.php"
</pre>

'''Note''': This method requires manual markdown-to-wikitext conversion and is more complex.

----

== Troubleshooting ==

=== Script Authentication Issues ===

If login fails:
==== Verify your MediaWiki username and password ====
== Check that your account has edit permissions ==
== Ensure the wiki is accessible from the VPS ==

=== Connection Issues ===

If you can't connect:
<pre class="lang-bash">
==== Test connectivity ====
curl -I http://10.8.0.2:8080
curl -I https://wiki.jb-vpn.uk

== Test API ==
curl "http://10.8.0.2:8080/api.php?action=query&meta=siteinfo&format=json"
</pre>

=== Permission Issues ===

Ensure your MediaWiki account has:
* </code>edit<code> permission

* </code>createpage` permission (if pages don't exist)

----

=== Updating the Main Page ===

To update the Main Page with links to all documentation:

<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

This will add a comprehensive list of all documentation pages to the Main Page.

=== Complete Workflow Example ===

Here's a complete example workflow for restructuring documentation:

<pre class="lang-bash">
==== 1. Preview orphaned pages that would be deleted ====
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== 2. Delete orphaned pages (if the preview looks correct) ==
python3 /root/wiki_manager.py --delete-orphaned -y

== 3. Upload all new/updated documentation ==
python3 /root/wiki_manager.py --upload --auto-comment

== 4. Update the Main Page with new documentation structure ==
python3 /root/wiki_manager.py --update-main-page

== Or do steps 3 and 4 together: ==
python3 /root/wiki_manager.py --upload --update-main-page --auto-comment
</pre>

----

[[Category:Documentation]]
[[Category:Documentation/Wiki Management]]

Cursor SSH:Setup

2026-01-01T13:44:55Z

Josh: Major update - troubleshooting guide: Cursor IDE SSH Connection Setup for Raspberry Pi (58 sections)

This guide explains how to configure Cursor IDE to connect to a Raspberry Pi through the VPS SSH port forward.

== Overview ==

Cursor IDE (like VS Code) supports remote development via SSH. To connect to your Raspberry Pi through the VPS:

<pre>
Your Computer → Cursor IDE → SSH → VPS:22223 → VPN Tunnel → Raspberry Pi (10.8.0.3:22)
</pre>

== Prerequisites ==

=== ✅ '''SSH Port Forward Configured''' (Already done) ===
* Port forward: <code>22223</code> → <code>10.8.0.3:22</code>

* Verify: <code>sudo ssh-forward list</code>

== ✅ '''IONOS Firewall Rule''' (Required) ==
* Port <code>22223</code> must be allowed in IONOS Cloud Panel

* See: [SSH Port Forwarding Guide](Ssh-Port-Forwarding.md)

== '''Raspberry Pi Requirements''': ==
* SSH server enabled

* Root SSH access enabled (see step 1)

* Network connectivity via VPN

== Step-by-Step Configuration ==

=== 1. Enable SSH and Root Access on Raspberry Pi ===

'''Enable SSH server (on Raspberry Pi):'''
<pre class="lang-bash">
sudo systemctl enable ssh
sudo systemctl start ssh
</pre>

'''Or via raspi-config:'''
<pre class="lang-bash">
sudo raspi-config
== Navigate to: Interfacing Options → SSH → Enable ==
</pre>

'''Enable root SSH access (on Raspberry Pi):'''
<pre class="lang-bash">
== Set root password (if not already set) ==
r

== Enable root login via SSH ==
sudo sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
== Or if using password auth: ==
sudo sed -i 's/#PermitRootLogin yes/PermitRootLogin yes/' /etc/ssh/sshd_config

== Restart SSH service ==
sudo systemctl restart ssh
</pre>

'''Verify SSH is running:'''
<pre class="lang-bash">
sudo systemctl status ssh
== Should show: active (running) ==
</pre>

'''Test root SSH access:'''
<pre class="lang-bash">
ssh root@localhost
== Should connect as root ==
</pre>

=== 2. Configure SSH on Your Local Machine ===

Create or edit <code>~/.ssh/config</code> on your local machine (where Cursor is installed):

<pre class="lang-bash">
==== On your local machine (not the VPS) ====
nano ~/.ssh/config
</pre>

Add the following configuration:

<pre>
Host raspberrypi
HostName 87.106.61.62
Port 22223
User root
IdentityFile ~/.ssh/id_rsa
ServerAliveInterval 60
ServerAliveCountMax 3
StrictHostKeyChecking no
UserKnownHostsFile ~/.ssh/known_hosts
</pre>

'''Configuration Options:'''
* <code>Host raspberrypi</code>: Alias name (use any name you prefer)

* <code>HostName 87.106.61.62</code>: Your VPS public IP

* <code>Port 22223</code>: External port for Raspberry Pi forward

* <code>User root</code>: Username on Raspberry Pi (using root for Cursor)

* <code>IdentityFile ~/.ssh/id_rsa</code>: Path to your SSH private key

* <code>ServerAliveInterval 60</code>: Keep connection alive (prevents timeouts)

=== 3. Set Up SSH Key Authentication (Recommended) ===

'''On your local machine:'''

==== '''Generate SSH key pair''' (if you don't have one): ====
<pre class="lang-bash">
ssh-keygen -t ed25519 -C "cursor-raspberrypi"
=== Or use RSA: ssh-keygen -t rsa -b 4096 ===
</pre>

== '''Copy public key to Raspberry Pi (as root):''' ==
<pre class="lang-bash">
ssh-copy-id -p 22223 root@87.106.61.62
=== Or manually: ===
cat ~/.ssh/id_ed25519.pub | ssh -p 22223 root@87.106.61.62 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
</pre>

== '''Test passwordless connection:''' ==
<pre class="lang-bash">
ssh -p 22223 root@87.106.61.62
=== Should connect without password prompt ===
</pre>

=== 4. Configure Cursor IDE ===

==== '''Install Remote SSH Extension''' (if not already installed): ====
* Open Cursor

* Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)

* Search for "Remote - SSH" or "Anysphere Remote SSH"

* Install the extension

== '''Connect to Raspberry Pi''': ==
* Press <code>F1</code> or <code>Ctrl+Shift+P</code> (Cmd+Shift+P on Mac)

* Type: <code>Remote-SSH: Connect to Host...</code>

* Select: <code>raspberrypi</code> (or the Host name from your SSH config)

* Or enter directly: <code>root@87.106.61.62:22223</code>

== '''First Connection Setup''': ==
* Cursor will install the Cursor server on the Raspberry Pi

* This may take a few minutes on first connection

* You'll see a notification: "Installing Cursor Server..."

== '''Select Platform''' (if prompted): ==
* Choose: <code>Linux</code> → <code>arm64</code> or <code>armv7l</code> (depending on your Pi model)

=== 5. Troubleshooting Connection Issues ===

==== Issue: Connection Timeout ====

'''Check IONOS Firewall:'''
* Verify port <code>22223</code> is allowed in IONOS Cloud Panel

* Check rule priority (lower numbers = higher priority)

'''Test SSH connection manually:'''
<pre class="lang-bash">
ssh -v -p 22223 root@87.106.61.62
</pre>

'''Check port forward on VPS:'''
<pre class="lang-bash">
== On VPS ==
sudo ssh-forward list
iptables -t nat -L PREROUTING -n | grep 22223
</pre>

==== Issue: "Permission Denied" ====

'''Verify SSH key is authorized:'''
<pre class="lang-bash">
===== On Raspberry Pi =====
cat ~/.ssh/authorized_keys
== Should contain your public key ==
</pre>

'''Check SSH server logs:'''
<pre class="lang-bash">
== On Raspberry Pi ==
sudo tail -f /var/log/auth.log
== Attempt connection and watch for errors ==
</pre>

'''Verify user permissions:'''
<pre class="lang-bash">
== On Raspberry Pi ==
ls -la ~/.ssh/
== Should be: drwx------ (700) for .ssh directory ==
== Should be: -rw------- (600) for authorized_keys ==
</pre>

==== Issue: Cursor Server Installation Fails ====

'''Clear Cursor server cache:'''
<pre class="lang-bash">
===== On Raspberry Pi =====
rm -rf ~/.cursor-server
</pre>

'''Check disk space:'''
<pre class="lang-bash">
== On Raspberry Pi ==
df -h
</pre>

'''Check Python/Node.js availability:'''
<pre class="lang-bash">
== On Raspberry Pi ==
python3 --version
node --version # If available
</pre>

==== Issue: Slow Connection ====

'''Optimize SSH config:'''
Add to <code>~/.ssh/config</code>:
<pre>
Host raspberrypi
Compression yes
IPQoS throughput
</pre>

'''Use SSH multiplexing:'''
<pre>
Host raspberrypi
ControlMaster auto
ControlPath ~/.ssh/control-%h-%p-%r
ControlPersist 10m
</pre>

=== 6. Verify Complete Setup ===

'''Test checklist:'''

* [ ] SSH port forward is active: <code>sudo ssh-forward list</code>

* [ ] IONOS firewall allows port 22223

* [ ] Can SSH manually: <code>ssh -p 22223 root@87.106.61.62</code>

* [ ] SSH key authentication works (no password prompt)

* [ ] Cursor can connect via Remote SSH

* [ ] Cursor server installed on Raspberry Pi

* [ ] Can open files and use terminal in Cursor

=== 7. Multiple Devices Configuration ===

If you have multiple devices, add separate entries in <code>~/.ssh/config</code>:

<pre>
Host synology
HostName 87.106.61.62
Port 22222
User admin
IdentityFile ~/.ssh/id_rsa

Host raspberrypi
HostName 87.106.61.62
Port 22223
User root
IdentityFile ~/.ssh/id_rsa

Host device-03
HostName 87.106.61.62
Port 22223
User user
IdentityFile ~/.ssh/id_rsa
</pre>

== Security Best Practices ==

'''Note''': This guide uses root user for Cursor connections to avoid permission issues. While convenient for development, be aware of security implications.

=== '''Use SSH Keys''': Always use key-based authentication instead of passwords ===
== '''Disable Password Auth for Root''': On Raspberry Pi, edit <code>/etc/ssh/sshd_config</code>: ==
<pre>
PermitRootLogin prohibit-password
PasswordAuthentication no
PubkeyAuthentication yes
</pre>
This allows root login only with SSH keys, not passwords.
Then restart: <code>sudo systemctl restart ssh</code>

== '''Use Strong Keys''': Use ED25519 or RSA 4096-bit keys ==
== '''Limit Access''': Consider restricting SSH access to specific IPs if possible ==
== '''Keep Updated''': Regularly update Raspberry Pi OS and SSH server ==
== '''Root Access Consideration''': Using root avoids permission issues in Cursor but increases security risk. Consider using a dedicated user with sudo if security is a concern. ==

== Advanced Configuration ==

=== SSH Config with Jump Host (Alternative) ===

If you want to connect through the VPS as a jump host:

<pre>
Host vps
HostName 87.106.61.62
User root
IdentityFile ~/.ssh/id_rsa

Host raspberrypi
HostName 10.8.0.3
User root
ProxyJump vps
IdentityFile ~/.ssh/id_rsa
</pre>

=== Port Forwarding in SSH Config ===

You can also create local port forwards in your SSH config:

<pre>
Host raspberrypi
HostName 87.106.61.62
Port 22223
User root
LocalForward 8080 localhost:8080 # Forward local port 8080 to Pi's 8080
</pre>

== Quick Reference ==

{| class="wikitable"
|-
| Component || Value
|-
| VPS Public IP || 87.106.61.62
|-
| Raspberry Pi External Port || 22223
|-
| Raspberry Pi VPN IP || 10.8.0.3
|-
| Raspberry Pi SSH Port || 22
|-
| Default User || root
|}
'''SSH Command:'''
<pre class="lang-bash">
ssh -p 22223 root@87.106.61.62
</pre>

'''Cursor Connection:'''
* Host: <code>raspberrypi</code> (from SSH config)

* Or: <code>root@87.106.61.62:22223</code>

== Related Documentation ==

* [SSH Port Forwarding Management](index.md)

* [OpenVPN Server Configuration](index.md)

* [Port Forwarding Troubleshooting](port-forwarding-troubleshooting.md)

----

[[Category:Documentation]]
[[Category:Documentation/Cursor SSH]]

OpenVPN:User Management

2026-01-01T13:44:54Z

Josh: Major update - troubleshooting guide: OpenVPN User Management (58 sections)

This document covers managing OpenVPN users (clients) including adding, removing, and managing client certificates.

== Overview ==

OpenVPN uses certificate-based authentication. Each user (client) requires:
* A unique client certificate

* A client configuration file (<code>.ovpn</code>)

* Optionally, a static IP assignment via CCD file

== Current Users ==

Client configuration files are stored in <code>/root/</code>:
* <code>josh.ovpn</code>

* <code>Work_MacBook_Air.ovpn</code>

* <code>StrawberryNAS.ovpn</code> (Synology NAS with static IP 10.8.0.2)

== Adding a New User ==

=== Method 1: Using the OpenVPN Install Script (Recommended) ===

If you have the <code>openvpn-install.sh</code> script available:

<pre class="lang-bash">
==== Run the installer script ====
bash /root/openvpn-install.sh

== Select option to add a new client ==
== Follow the prompts to enter the client name ==
== The script will automatically: ==
== - Generate the client certificate ==
== - Create the .ovpn configuration file ==
== - Place it in /root/ ==
</pre>

=== Method 2: Manual Certificate Creation with Easy-RSA ===

For manual certificate creation:

==== '''Navigate to Easy-RSA directory''': ====
<pre class="lang-bash">
cd /etc/openvpn/server/easy-rsa/
</pre>

== '''Generate client certificate and key''': ==
<pre class="lang-bash">
./easyrsa build-client-full clientname nopass
</pre>

Replace <code>clientname</code> with the desired client name (e.g., <code>newuser</code>, <code>laptop-john</code>).

The <code>nopass</code> option creates a certificate without a password. Remove it if you want password protection.

== '''Create client configuration file''': ==

You'll need to create a <code>.ovpn</code> file that combines:
* Client certificate

* Client private key

* CA certificate

* TLS-Crypt key

* Connection settings

Use an existing <code>.ovpn</code> file as a template:
<pre class="lang-bash">
cp /root/josh.ovpn /root/newclient.ovpn
</pre>

Then extract and replace the certificate sections:
<pre class="lang-bash">
=== Extract client certificate from Easy-RSA ===
cat /etc/openvpn/server/easy-rsa/pki/issued/clientname.crt

=== Extract client key ===
cat /etc/openvpn/server/easy-rsa/pki/private/clientname.key

=== Replace the <cert> and <key> sections in the .ovpn file ===
</pre>

== '''Verify the configuration''': ==
<pre class="lang-bash">
=== Test the .ovpn file syntax ===
openvpn --config /root/newclient.ovpn --test-crypto
</pre>

=== Method 3: Using Easy-RSA Helper Script ===

Create a helper script to automate the process:

<pre class="lang-bash">
#!/bin/bash
== /root/create-openvpn-client.sh ==

CLIENT_NAME=$1

if [ -z "$CLIENT_NAME" ]; then
echo "Usage: $0 <client-name>"
exit 1
fi

cd /etc/openvpn/server/easy-rsa/

== Generate client certificate ==
./easyrsa build-client-full "$CLIENT_NAME" nopass

== Create .ovpn file ==
CLIENT_DIR="/root"
OVPN_FILE="$CLIENT_DIR/$CLIENT_NAME.ovpn"

== Start with common client configuration ==
cat > "$OVPN_FILE" << EOF
client
dev tun
proto udp
remote 87.106.61.62 1194
resolv-retry infinite
nobind
persist-key
persist-tun
remote-cert-tls server
auth SHA512
ignore-unknown-option block-outside-dns
verb 3
EOF

== Add CA certificate ==
echo "<ca>" >> "$OVPN_FILE"
cat /etc/openvpn/server/ca.crt >> "$OVPN_FILE"
echo "</ca>" >> "$OVPN_FILE"

== Add client certificate ==
echo "<cert>" >> "$OVPN_FILE"
cat "/etc/openvpn/server/easy-rsa/pki/issued/$CLIENT_NAME.crt" >> "$OVPN_FILE"
echo "</cert>" >> "$OVPN_FILE"

== Add client key ==
echo "<key>" >> "$OVPN_FILE"
cat "/etc/openvpn/server/easy-rsa/pki/private/$CLIENT_NAME.key" >> "$OVPN_FILE"
echo "</key>" >> "$OVPN_FILE"

== Add TLS-Crypt key ==
echo "<tls-crypt>" >> "$OVPN_FILE"
cat /etc/openvpn/server/tc.key >> "$OVPN_FILE"
echo "</tls-crypt>" >> "$OVPN_FILE"

echo "Client configuration created: $OVPN_FILE"
echo "Send this file securely to the client."
</pre>

Make it executable:
<pre class="lang-bash">
chmod +x /root/create-openvpn-client.sh
</pre>

Usage:
<pre class="lang-bash">
/root/create-openvpn-client.sh newclientname
</pre>

== Assigning Static IP Addresses ==

To assign a static IP address to a client:

=== '''Create a CCD file''' in <code>/etc/openvpn/ccd/</code>: ===
<pre class="lang-bash">
sudo nano /etc/openvpn/ccd/clientname
</pre>

== '''Add IP assignment''': ==
<pre>
ifconfig-push 10.8.0.X 255.255.255.0
</pre>

Replace <code>X</code> with the desired IP (e.g., <code>10.8.0.10</code>).

== '''Set proper permissions''': ==
<pre class="lang-bash">
sudo chown nobody:nogroup /etc/openvpn/ccd/clientname
sudo chmod 600 /etc/openvpn/ccd/clientname
</pre>

== '''Restart OpenVPN''' (if needed): ==
<pre class="lang-bash">
sudo systemctl restart openvpn
</pre>

'''Example''': The Synology NAS has a CCD file at <code>/etc/openvpn/ccd/StrawberryNAS</code> with:
<pre>
ifconfig-push 10.8.0.2 255.255.255.0
</pre>

== Listing Active Users ==

To see which users are currently connected:

<pre class="lang-bash">
=== View IP persistence file (shows last assigned IPs) ===
cat /etc/openvpn/server/ipp.txt

== Check active connections via system logs ==
journalctl -u openvpn | grep "Peer Connection Initiated"

== Or check the VPN interface ==
ip addr show tun0
</pre>

== Revoking a User Certificate ==

When a user should no longer have access:

=== '''Navigate to Easy-RSA directory''': ===
<pre class="lang-bash">
cd /etc/openvpn/server/easy-rsa/
</pre>

== '''Revoke the certificate''': ==
<pre class="lang-bash">
./easyrsa revoke clientname
</pre>

You'll be prompted to confirm. Type <code>yes</code>.

== '''Update the Certificate Revocation List (CRL)''': ==
<pre class="lang-bash">
./easyrsa gen-crl
</pre>

== '''Copy the updated CRL to the server directory''': ==
<pre class="lang-bash">
cp pki/crl.pem /etc/openvpn/server/crl.pem
</pre>

== '''Restart OpenVPN''' to apply the revocation: ==
<pre class="lang-bash">
systemctl restart openvpn
</pre>

== '''Remove client files''' (optional but recommended): ==
<pre class="lang-bash">
=== Remove .ovpn file ===
rm /root/clientname.ovpn

=== Remove CCD file if it exists ===
rm /etc/openvpn/ccd/clientname
</pre>

'''Note''': The revoked certificate will be immediately rejected. The user will not be able to connect even if they still have the <code>.ovpn</code> file.

== Security Best Practices ==

=== '''Use descriptive client names''': Use names that identify the device/user (e.g., <code>laptop-john</code>, <code>phone-mary</code>, <code>nas-synology</code>) ===

== '''Regular certificate rotation''': Renew certificates before expiration (typically annually) ==

== '''Revoke unused certificates''': Remove access for users who no longer need VPN access ==

== '''Secure .ovpn file distribution''': Use secure channels (encrypted email, secure file transfer) when sending <code>.ovpn</code> files to clients ==

== '''Limit static IP assignments''': Only assign static IPs when necessary (e.g., for services like the Synology NAS) ==

== '''Monitor active connections''': Regularly check who is connected and verify it's expected ==

== '''Keep Easy-RSA secure''': The Easy-RSA directory contains sensitive keys - restrict access: ==
<pre class="lang-bash">
chmod 700 /etc/openvpn/server/easy-rsa/
</pre>

== Backup User Certificates ==

Before making changes, backup user certificates:

<pre class="lang-bash">
=== Backup all certificates and keys ===
tar -czf openvpn-users-backup-$(date +%Y%m%d).tar.gz \
/etc/openvpn/server/easy-rsa/pki/ \
/root/*.ovpn \
/etc/openvpn/ccd/
</pre>

== Related Documentation ==

* [Server Configuration](server-configuration.md) - Server setup

* [Client Configuration](client-configuration.md) - Client setup

* [Certificate Management](certificate-management.md) - Certificate details

* [[Documentation:Index|Troubleshooting]] - User management troubleshooting

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]

OpenVPN:Integration

2026-01-01T13:44:54Z

Josh: Major update - configuration guide: OpenVPN Integration with Reverse Proxy (27 sections)

This document describes how the OpenVPN server integrates with the reverse proxy system.

== Integration Overview ==

The OpenVPN server is essential for the reverse proxy system:

=== '''Synology NAS connects''' via VPN (10.8.0.2) ===
== '''Nginx reverse proxy''' forwards requests to 10.8.0.2 ==
== '''Services are accessible''' via public subdomains without direct internet exposure ==
== '''All traffic is encrypted''' through the VPN tunnel ==

== Network Flow ==

<pre>
Internet → VPS (87.106.61.62)
→ Nginx Reverse Proxy
→ OpenVPN Tunnel (tun0: 10.8.0.1 → 10.8.0.2)
→ Synology NAS Services
</pre>

== How It Works ==

=== Client accesses a public subdomain (e.g., <code>wiki.jb-vpn.uk</code>) ===
== DNS resolves to VPS public IP (87.106.61.62) ==
== Nginx receives the request on port 443 (HTTPS) ==
== SSL is terminated at the VPS ==
== Nginx forwards the request through the OpenVPN tunnel to the Synology NAS (10.8.0.2) ==
== The service on the Synology NAS responds ==
== The response travels back through the VPN tunnel ==
== Nginx sends the response to the client ==

== Benefits ==

* '''No Direct Exposure''': Synology NAS is not directly accessible from the internet

* '''Encrypted Tunnel''': All traffic between VPS and NAS is encrypted via OpenVPN

* '''Secure Access''': Services are accessible via HTTPS while remaining isolated

* '''Centralized Management''': All services accessible through a single VPS

== Requirements ==

For the integration to work:

=== '''OpenVPN server must be running''' on the VPS ===
== '''Synology NAS must be connected''' to the VPN (10.8.0.2) ==
== '''VPN tunnel must be active''' (tun0 interface up) ==
== '''Nginx must be configured''' to forward to 10.8.0.2 ==

== Verification ==

Check that the integration is working:

<pre class="lang-bash">
=== Check VPN is running ===
systemctl status openvpn

== Check VPN interface ==
ip addr show tun0

== Check Synology is connected ==
ping -c 2 10.8.0.2

== Check Nginx can reach Synology ==
curl http://10.8.0.2:8080
</pre>

== Related Documentation ==

* [System Overview](index.md) - Overall system architecture

* [Server Configuration](server-configuration.md) - OpenVPN server setup

* [Adding Services](index.md) - Configuring services

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]

OpenVPN:Client Configuration

2026-01-01T13:44:53Z

Josh: Content added - configuration guide: OpenVPN Client Configuration (15 sections) (configuration)

This document describes how to configure OpenVPN clients.

== Client Files ==

Client configuration files (<code>.ovpn</code>) are stored in <code>/root/</code>:

* <code>josh.ovpn</code>

* <code>Work_MacBook_Air.ovpn</code>

* <code>StrawberryNAS.ovpn</code> (Synology NAS)

== Client Configuration Structure ==

Each client <code>.ovpn</code> file contains:
* Client certificate

* Client private key

* CA certificate

* TLS-Crypt key

* Connection settings (server IP, port, protocol)

== Client Configuration Directory ==

Per-client configurations can be placed in <code>/etc/openvpn/ccd/</code> to assign static IP addresses or custom routes.

'''Current CCD Files''':
* <code>StrawberryNAS</code> - Static IP configuration for Synology NAS (10.8.0.2)

=== Example CCD File ===

Example CCD file content:
<pre>
ifconfig-push 10.8.0.2 255.255.255.0
</pre>

This assigns a static IP address (10.8.0.2) to the client named "StrawberryNAS". The second parameter is the netmask for the VPN subnet.

== Client Connection ==

=== Connecting from Client ===

==== '''Install OpenVPN client''' on the device ====
== '''Import the <code>.ovpn</code> file''' into the OpenVPN client ==
== '''Connect''' using the client application ==

=== Synology NAS Connection ===

The Synology NAS connects using <code>StrawberryNAS.ovpn</code> and typically receives IP address 10.8.0.2.

=== Verifying Connection ===

From the server, verify client is connected:

<pre class="lang-bash">
==== Check connected clients ====
cat /etc/openvpn/server/ipp.txt

== Check VPN interface ==
ip addr show tun0

== Ping client ==
ping 10.8.0.2
</pre>

== Related Documentation ==

* [Server Configuration](server-configuration.md) - Server setup

* [User Management](user-management.md) - Adding new clients

* [Certificate Management](certificate-management.md) - Certificate details

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]

OpenVPN:Server Configuration

2026-01-01T13:44:52Z

Josh: Content added - troubleshooting guide: OpenVPN Server Configuration (22 sections) (configuration)

This document describes the OpenVPN server configuration and setup.

== Network Details ==

* '''Server IP''': 10.8.0.1 (on tun0 interface)

* '''VPN Network''': 10.8.0.0/24

* '''Public IP''': 87.106.61.62

* '''Port''': 1194 (UDP)

* '''Protocol''': UDP

== Server Files Location ==

All OpenVPN server files are located in <code>/etc/openvpn/server/</code>:

* <code>server.conf</code> - Main server configuration

* <code>ca.crt</code> - Certificate Authority certificate

* <code>ca.key</code> - Certificate Authority private key

* <code>server.crt</code> - Server certificate

* <code>server.key</code> - Server private key

* <code>dh.pem</code> - Diffie-Hellman parameters

* <code>tc.key</code> - TLS-Crypt key (for additional security)

* <code>crl.pem</code> - Certificate Revocation List

* <code>ipp.txt</code> - IP address persistence file

* <code>easy-rsa/</code> - Easy-RSA directory for certificate management

== Server Configuration File ==

The main configuration is in <code>/etc/openvpn/server/server.conf</code>:

<pre class="lang-conf">
local 87.106.61.62
port 1194
proto udp
dev tun
ca ca.crt
cert server.crt
key server.key
dh dh.pem
auth SHA512
tls-crypt tc.key
topology subnet
server 10.8.0.0 255.255.255.0
push "redirect-gateway def1 bypass-dhcp"
ifconfig-pool-persist ipp.txt
push "dhcp-option DNS 212.227.123.16"
push "dhcp-option DNS 212.227.123.17"
push "block-outside-dns"
keepalive 10 120
user nobody
group nogroup
persist-key
persist-tun
verb 3
crl-verify crl.pem
explicit-exit-notify
client-config-dir /etc/openvpn/ccd
script-security 2
up /etc/openvpn/iptables-restore.sh
</pre>

== Key Configuration Options ==

* '''<code>local 87.106.61.62</code>''': Binds to the VPS public IP address

* '''<code>port 1194</code>''': Standard OpenVPN port (UDP)

* '''<code>server 10.8.0.0 255.255.255.0</code>''': Defines the VPN subnet

* '''<code>push "redirect-gateway def1 bypass-dhcp"</code>''': Routes all client traffic through VPN

* '''<code>client-config-dir /etc/openvpn/ccd</code>''': Directory for per-client configurations

* '''<code>crl-verify crl.pem</code>''': Certificate revocation list for security

* '''<code>tls-crypt tc.key</code>''': Additional encryption layer

== Network Configuration ==

=== VPN Interface ===

The VPN creates a TUN interface (<code>tun0</code>):

<pre class="lang-bash">
ip addr show tun0
</pre>

'''Output''':
<pre>
3: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500
inet 10.8.0.1/24 scope global tun0
</pre>

=== IP Address Assignment ===

* '''Server''': 10.8.0.1

* '''Clients''': 10.8.0.2 - 10.8.0.254 (dynamically assigned)

* '''Synology NAS''': Typically 10.8.0.2 (may be static via CCD)

=== Routing ===

The server uses iptables for NAT and routing:

'''NAT Rules''':
<pre class="lang-bash">
iptables -t nat -L -n -v
</pre>

'''Key Rules''':
* '''SNAT''': Masquerades VPN client traffic (10.8.0.0/24) to VPS public IP

* '''MASQUERADE''': Allows VPN clients to access internet through VPS

== Firewall Configuration ==

=== Required Ports ===

Ensure UDP port 1194 is open:

<pre class="lang-bash">
==== Check if port is listening ====
ss -ulnp | grep 1194

== Check firewall rules ==
iptables -L INPUT -n -v | grep 1194
ufw status | grep 1194 # if using ufw
</pre>

=== iptables Rules ===

The OpenVPN server uses an iptables restore script (<code>/etc/openvpn/iptables-restore.sh</code>) that runs when the VPN starts.

== Service Management ==

=== Service Status ===

Check OpenVPN service status:
<pre class="lang-bash">
systemctl status openvpn
</pre>

=== Start/Stop/Restart ===

<pre class="lang-bash">
==== Start OpenVPN ====
systemctl start openvpn

== Stop OpenVPN ==
systemctl stop openvpn

== Restart OpenVPN ==
systemctl restart openvpn

== Reload configuration (graceful) ==
systemctl reload openvpn
</pre>

The OpenVPN service is enabled to start on boot:
<pre class="lang-bash">
systemctl is-enabled openvpn
== Output: enabled ==
</pre>

== Related Documentation ==

* [Client Configuration](client-configuration.md) - Client setup

* [User Management](user-management.md) - Managing users

* [Certificate Management](certificate-management.md) - Certificate management

* [[Documentation:Index|Troubleshooting]] - Server troubleshooting

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]

OpenVPN:Certificate Management

2026-01-01T13:44:51Z

Josh: Major update - troubleshooting guide: OpenVPN Certificate Management (31 sections)

This document describes certificate management for OpenVPN.

== Certificate Authority ==

The server uses Easy-RSA 3 for certificate management. The Easy-RSA directory is located at <code>/etc/openvpn/server/easy-rsa/</code>.

== Easy-RSA Commands Reference ==

Common Easy-RSA commands:

<pre class="lang-bash">
cd /etc/openvpn/server/easy-rsa/

=== Build a new CA (only needed once) ===
./easyrsa build-ca

== Generate Diffie-Hellman parameters (only needed once) ==
./easyrsa gen-dh

== Build server certificate (already done) ==
./easyrsa build-server-full server nopass

== Build client certificate ==
./easyrsa build-client-full clientname nopass

== Revoke a certificate ==
./easyrsa revoke clientname

== Generate/update CRL ==
./easyrsa gen-crl

== Show certificate details ==
./easyrsa show-cert clientname

== List all certificates ==
ls -la pki/issued/
</pre>

== Viewing All Certificates ==

To list all issued certificates:

<pre class="lang-bash">
cd /etc/openvpn/server/easy-rsa/
./easyrsa show-cert clientname
</pre>

To list all certificates in the PKI:

<pre class="lang-bash">
ls -la /etc/openvpn/server/easy-rsa/pki/issued/
</pre>

== Checking Certificate Expiration ==

To check when a certificate expires:

<pre class="lang-bash">
cd /etc/openvpn/server/easy-rsa/

=== View certificate details ===
openssl x509 -in pki/issued/clientname.crt -noout -dates

== Or use Easy-RSA ==
./easyrsa show-cert clientname | grep -i "not after"
</pre>

== Renewing an Expired Certificate ==

If a certificate is about to expire or has expired:

=== '''Revoke the old certificate''' (if expired): ===
<pre class="lang-bash">
cd /etc/openvpn/server/easy-rsa/
./easyrsa revoke clientname
./easyrsa gen-crl
cp pki/crl.pem /etc/openvpn/server/crl.pem
</pre>

== '''Generate a new certificate''': ==
<pre class="lang-bash">
./easyrsa build-client-full clientname nopass
</pre>

== '''Update the .ovpn file''' with the new certificate: ==
<pre class="lang-bash">
=== Extract new certificate ===
cat pki/issued/clientname.crt

=== Update the <cert> section in the .ovpn file ===
nano /root/clientname.ovpn
</pre>

== '''Distribute the updated .ovpn file''' to the client ==

== '''Restart OpenVPN''': ==
<pre class="lang-bash">
systemctl restart openvpn
</pre>

== Certificate Revocation ==

See [user-management.md#revoking-a-user-certificate User Management] for details on revoking certificates.

== Backup and Recovery ==

=== Backup Important Files ===

<pre class="lang-bash">
==== Backup server configuration and certificates ====
tar -czf openvpn-backup-$(date +%Y%m%d).tar.gz \
/etc/openvpn/server/ \
/etc/openvpn/ccd/ \
/root/''.ovpn
</pre>

=== Restore from Backup ===

==== Extract backup: ====
<pre class="lang-bash">
tar -xzf openvpn-backup-YYYYMMDD.tar.gz -C /
</pre>

== Verify file permissions: ==
<pre class="lang-bash">
chmod 600 /etc/openvpn/server/''.key
chmod 644 /etc/openvpn/server/*.crt
</pre>

== Restart OpenVPN: ==
<pre class="lang-bash">
systemctl restart openvpn
</pre>

== Related Documentation ==

* [User Management](user-management.md) - Managing users and certificates

* [Server Configuration](server-configuration.md) - Server setup

* [[Documentation:Index|Troubleshooting]] - Certificate troubleshooting

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]

OpenVPN:Raspberry Pi Auto Connect

2026-01-01T13:44:50Z

Josh: Major update - troubleshooting guide: Raspberry Pi OpenVPN Auto-Connect Setup (44 sections)

This guide walks through setting up a Raspberry Pi to automatically connect to the OpenVPN server when it boots. This assumes the Raspberry Pi is being set up from scratch with only the OS installed.

== Prerequisites ==

* Raspberry Pi with Raspberry Pi OS installed (Raspberry Pi OS Lite or Desktop)

* SSH access to the Raspberry Pi (or physical access with keyboard/monitor)

* OpenVPN client configuration file (<code>.ovpn</code>) from the server administrator

* Network connectivity on the Raspberry Pi

== Step 1: Initial System Setup ==

=== 1.1 Update System Packages ===

First, ensure your Raspberry Pi is up to date:

<pre class="lang-bash">
sudo apt update
sudo apt upgrade -y
</pre>

=== 1.2 Install Required Packages ===

Install OpenVPN and other necessary tools:

<pre class="lang-bash">
sudo apt install -y openvpn network-manager-openvpn resolvconf
</pre>

'''Note''': The <code>network-manager-openvpn</code> package is optional but can be useful for GUI-based management. The <code>resolvconf</code> package helps manage DNS resolution when connected to the VPN.

== Step 2: Obtain OpenVPN Configuration File ==

You need to obtain the <code>.ovpn</code> configuration file for your Raspberry Pi from the server administrator. This file contains:

* Client certificate

* Client private key

* CA certificate

* TLS-Crypt key

* Server connection details

'''Common file locations on the server''': <code>/root/<client-name>.ovpn</code>

=== 2.1 Transfer Configuration File to Raspberry Pi ===

You can transfer the file using one of these methods:

'''Method 1: Using SCP (from your local machine)'''

<pre class="lang-bash">
scp <username>@<raspberry-pi-ip>:/path/to/client.ovpn ~/client.ovpn
</pre>

'''Method 2: Using SFTP'''

<pre class="lang-bash">
sftp <username>@<raspberry-pi-ip>
put /path/to/client.ovpn ~/client.ovpn
exit
</pre>

'''Method 3: Copy and paste (if you have the file contents)'''

Create the file manually:

<pre class="lang-bash">
nano ~/client.ovpn
</pre>

Paste the contents and save (Ctrl+X, then Y, then Enter).

== Step 3: Install Configuration File ==

=== 3.1 Copy Configuration to System Directory ===

Copy the <code>.ovpn</code> file to <code>/etc/openvpn/client/</code>:

<pre class="lang-bash">
sudo cp ~/client.ovpn /etc/openvpn/client/client.conf
</pre>

'''Note''': OpenVPN looks for <code>.conf</code> files in <code>/etc/openvpn/client/</code>, so we rename it to <code>client.conf</code>. If you have multiple VPN configurations, you can use descriptive names like <code>raspberry-pi.conf</code>.

=== 3.2 Set Proper Permissions ===

Ensure the configuration file has the correct permissions:

<pre class="lang-bash">
sudo chmod 600 /etc/openvpn/client/client.conf
sudo chown root:root /etc/openvpn/client/client.conf
</pre>

== Step 4: Configure Auto-Start on Boot ==

=== 4.1 Enable OpenVPN Service ===

Enable the OpenVPN client service to start automatically on boot:

<pre class="lang-bash">
sudo systemctl enable openvpn-client@client.service
</pre>

'''Note''': The service name format is <code>openvpn-client@<config-name>.service</code>, where <code><config-name></code> is the name of your <code>.conf</code> file without the extension. Since we named it <code>client.conf</code>, the service is <code>openvpn-client@client.service</code>.

=== 4.2 Start the Service ===

Start the OpenVPN service immediately (without rebooting):

<pre class="lang-bash">
sudo systemctl start openvpn-client@client.service
</pre>

=== 4.3 Verify Service Status ===

Check that the service is running:

<pre class="lang-bash">
sudo systemctl status openvpn-client@client.service
</pre>

You should see output indicating the service is active and running.

== Step 5: Configure Auto-Reconnect ==

OpenVPN should automatically reconnect if the connection drops, but we can enhance this by modifying the configuration file.

=== 5.1 Add Auto-Reconnect Options ===

Edit the configuration file:

<pre class="lang-bash">
sudo nano /etc/openvpn/client/client.conf
</pre>

Add these lines at the end of the file (if they're not already present):

<pre>
== Auto-reconnect settings ==
keepalive 10 120
persist-key
persist-tun
resolv-retry infinite
</pre>

'''Explanation''':
* <code>keepalive 10 120</code>: Sends a ping every 10 seconds, restarts if no response for 120 seconds

* <code>persist-key</code>: Keeps trying to read key files if they're temporarily unavailable

* <code>persist-tun</code>: Keeps the TUN/TAP interface open across restarts

* <code>resolv-retry infinite</code>: Keeps trying to resolve the server hostname if DNS fails

Save and exit (Ctrl+X, then Y, then Enter).

=== 5.2 Restart the Service ===

Apply the changes:

<pre class="lang-bash">
sudo systemctl restart openvpn-client@client.service
</pre>

== Step 6: Verify Connection ==

=== 6.1 Check VPN Interface ===

Verify that the VPN interface (typically <code>tun0</code>) is up:

<pre class="lang-bash">
ip addr show tun0
</pre>

You should see output showing the VPN interface with an IP address in the VPN subnet (e.g., <code>10.8.0.x</code>).

=== 6.2 Check Routing ===

Verify that traffic is being routed through the VPN:

<pre class="lang-bash">
ip route show
</pre>

You should see routes indicating traffic is going through the <code>tun0</code> interface.

=== 6.3 Test Connectivity ===

Test connectivity to the VPN server:

<pre class="lang-bash">
==== Ping the VPN server (adjust IP based on your VPN subnet) ====
ping -c 4 10.8.0.1
</pre>

=== 6.4 Check OpenVPN Logs ===

View OpenVPN logs to ensure everything is working:

<pre class="lang-bash">
sudo journalctl -u openvpn-client@client.service -f
</pre>

Press Ctrl+C to exit the log viewer.

== Step 7: Test Auto-Start on Boot ==

=== 7.1 Reboot the Raspberry Pi ===

Reboot to verify the VPN connects automatically:

<pre class="lang-bash">
sudo reboot
</pre>

=== 7.2 Verify After Reboot ===

After the Raspberry Pi reboots, SSH back in and verify:

<pre class="lang-bash">
==== Check service status ====
sudo systemctl status openvpn-client@client.service

== Check VPN interface ==
ip addr show tun0

== Check routing ==
ip route show
</pre>

== Troubleshooting ==

=== VPN Not Connecting on Boot ===

If the VPN doesn't connect automatically on boot, check:

# '''Service Status''':
<pre class="lang-bash">
sudo systemctl status openvpn-client@client.service
</pre>

# '''Service Logs''':
<pre class="lang-bash">
sudo journalctl -u openvpn-client@client.service -n 50
</pre>

# '''Network Timing''': The VPN service might be starting before the network is ready. Check if <code>network-online.target</code> is enabled:
<pre class="lang-bash">
sudo systemctl enable NetworkManager-wait-online.service
=== Or for systemd-networkd: ===
sudo systemctl enable systemd-networkd-wait-online.service
</pre>

=== VPN Interface Not Appearing ===

If <code>tun0</code> doesn't appear:

# '''Check if OpenVPN is running''':
<pre class="lang-bash">
ps aux | grep openvpn
</pre>

# '''Check configuration file syntax''':
<pre class="lang-bash">
sudo openvpn --config /etc/openvpn/client/client.conf --verb 4
</pre>

# '''Verify TUN/TAP module is loaded''':
<pre class="lang-bash">
lsmod | grep tun
</pre>

If not loaded, load it:
<pre class="lang-bash">
sudo modprobe tun
</pre>

=== DNS Resolution Issues ===

If DNS isn't working after connecting:

# '''Check DNS settings''':
<pre class="lang-bash">
cat /etc/resolv.conf
</pre>

# '''Install resolvconf if not already installed''':
<pre class="lang-bash">
sudo apt install resolvconf
</pre>

# '''Restart the OpenVPN service''':
<pre class="lang-bash">
sudo systemctl restart openvpn-client@client.service
</pre>

=== Connection Drops Frequently ===

If the connection drops frequently:

# '''Check network stability''':
<pre class="lang-bash">
ping -c 10 <vpn-server-ip>
</pre>

# '''Review keepalive settings''' in the configuration file

# '''Check firewall rules''' that might be blocking OpenVPN traffic

# '''Review server logs''' on the VPN server for any issues

=== Permission Denied Errors ===

If you see permission errors:

# '''Verify file permissions''':
<pre class="lang-bash">
ls -l /etc/openvpn/client/client.conf
</pre>

Should show <code>-rw-------</code> (600) and owned by <code>root:root</code>

# '''Check directory permissions''':
<pre class="lang-bash">
ls -ld /etc/openvpn/client/
</pre>

== Advanced Configuration ==

=== Multiple VPN Configurations ===

If you need multiple VPN configurations:

# Copy additional <code>.ovpn</code> files to <code>/etc/openvpn/client/</code> with different names:
<pre class="lang-bash">
sudo cp ~/vpn2.ovpn /etc/openvpn/client/vpn2.conf
</pre>

# Enable the additional service:
<pre class="lang-bash">
sudo systemctl enable openvpn-client@vpn2.service
sudo systemctl start openvpn-client@vpn2.service
</pre>

=== Custom DNS Servers ===

To use custom DNS servers when connected to the VPN, add to your configuration file:

<pre>
dhcp-option DNS 8.8.8.8
dhcp-option DNS 8.8.4.4
</pre>

=== Route Specific Traffic Through VPN ===

To route only specific traffic through the VPN (split tunneling), modify the configuration file to remove or comment out:

<pre>
==== Redirect all traffic through VPN (remove or comment this line) ====
== redirect-gateway def1 ==
</pre>

Then add specific routes:

<pre>
route 192.168.1.0 255.255.255.0
</pre>

== Security Considerations ==

# '''Protect Configuration Files''': The <code>.ovpn</code> file contains private keys. Ensure it has restrictive permissions (600) and is owned by root.

# '''Regular Updates''': Keep your Raspberry Pi OS and OpenVPN client updated:
<pre class="lang-bash">
sudo apt update && sudo apt upgrade -y
</pre>

# '''Firewall''': Consider configuring a firewall (ufw) to allow only necessary traffic.

# '''Monitor Logs''': Regularly check OpenVPN logs for any suspicious activity.

== Summary ==

After completing these steps, your Raspberry Pi will:

* Automatically connect to the OpenVPN server on boot

* Automatically reconnect if the connection drops

* Maintain the VPN connection as long as the device is powered on

'''Key Files''':
* Configuration: <code>/etc/openvpn/client/client.conf</code>

* Service: <code>openvpn-client@client.service</code>

* Logs: <code>journalctl -u openvpn-client@client.service</code>

'''Useful Commands''':
* Start VPN: <code>sudo systemctl start openvpn-client@client.service</code>

* Stop VPN: <code>sudo systemctl stop openvpn-client@client.service</code>

* Restart VPN: <code>sudo systemctl restart openvpn-client@client.service</code>

* Check Status: <code>sudo systemctl status openvpn-client@client.service</code>

* View Logs: <code>sudo journalctl -u openvpn-client@client.service -f</code>

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]

Troubleshooting:Port Forwarding Troubleshooting

2026-01-01T13:44:49Z

Josh: Major update - troubleshooting guide: Port Forwarding Troubleshooting Guide (108 sections) (troubleshooting)

== Overview ==

This guide covers troubleshooting for SSH port forwarding from the VPS (port 22222) to the Synology NAS (10.8.0.2:22) via OpenVPN.

'''Port Forwarding Configuration:'''
* '''External Access''': <code>ssh -p 22222 user@87.106.61.62</code>

* '''Internal Target''': <code>10.8.0.2:22</code> (Synology NAS via VPN)

* '''Network Interface''': <code>ens6</code> (external interface)

* '''VPN Interface''': <code>tun0</code> (OpenVPN tunnel)

* '''Cloud Provider''': IONOS

----

== IONOS Cloud Provider Configuration ==

'''Important:''' This VPS is running on IONOS. The IONOS firewall must be configured to allow traffic on port 22222.

=== IONOS Firewall Configuration ===

IONOS uses a cloud firewall that must be configured through the IONOS Cloud Panel:

==== '''Log in to IONOS Cloud Panel:''' ====
* Navigate to: https://dcd.ionos.com/

* Select your Data Center → Server & Cloud → Servers

== '''Configure Firewall Rules:''' ==
* Select your VPS server

* Go to '''Firewall''' section

* Click '''Add Rule''' or edit existing rules

== '''Add Firewall Rule for Port 22222:''' ==
* '''Name''': SSH Port Forward (or any descriptive name)

* '''Protocol''': TCP

* '''Port''': 22222

* '''Source''': 0.0.0.0/0 (or restrict to specific IPs for security)

* '''Action''': Allow

* '''Priority''': Set appropriate priority (lower numbers = higher priority)

== '''Apply Changes:''' ==
* Save the firewall rule

* Changes are applied immediately (no server restart required)

== '''Verify IONOS Firewall:''' ==
* Ensure the firewall rule is active and enabled

* Check that no higher-priority DROP rules are blocking the port

* Verify the rule applies to the correct network interface

=== IONOS-Specific Notes ===

* '''Firewall Location''': IONOS firewall is managed at the cloud infrastructure level, not on the VPS

* '''No Security Groups''': IONOS uses a direct firewall per server, not security groups

* '''Rule Priority''': Lower priority numbers are evaluated first

* '''Immediate Effect''': Firewall changes take effect immediately without server restart

* '''Multiple Rules''': You can have multiple rules; ensure no conflicting DROP rules have higher priority

=== Testing IONOS Firewall ===

If you suspect the IONOS firewall is blocking traffic:

==== '''Check IONOS Cloud Panel:''' ====
* Verify the firewall rule exists and is enabled

* Check rule priority (lower numbers = higher priority)

* Ensure no DROP rules are blocking the port

== '''Test from different locations:''' ==
<pre class="lang-bash">
=== Test from external IP (not from the VPS itself) ===
ssh -v -p 22222 user@87.106.61.62
</pre>

== '''Check if packets reach the VPS:''' ==
<pre class="lang-bash">
=== On the VPS, check if packets are hitting iptables rules ===
iptables -t nat -L PREROUTING -n -v | grep 22222
=== If packet count doesn't increase, packets are blocked before reaching VPS ===
</pre>

----

== Quick Verification Checklist ==

Run these commands to verify the setup is working:

<pre class="lang-bash">
=== 1. Check if VPN is running ===
systemctl status openvpn-server@server.service

== 2. Verify VPN tunnel is up ==
ip addr show tun0

== 3. Check if Synology is connected to VPN ==
ping -c 2 10.8.0.2
cat /etc/openvpn/server/ipp.txt | grep "10.8.0.2"

== 4. Verify iptables rules are active ==
iptables -t nat -L PREROUTING -n -v | grep 22222
iptables -t filter -L FORWARD -n -v | grep "10.8.0.2"

== 5. Check IP forwarding is enabled ==
cat /proc/sys/net/ipv4/ip_forward # Should output: 1

== 6. Verify SSH is NOT listening on port 22222 (should only be on 22) ==
ss -tlnp | grep 22222 # Should return nothing
</pre>

----

== Components Explained ==

=== 1. iptables NAT Rules (Port Forwarding) ===

'''DNAT Rule (PREROUTING):'''
<pre class="lang-bash">
iptables -t nat -A PREROUTING -i ens6 -p tcp --dport 22222 -j DNAT --to-destination 10.8.0.2:22
</pre>
* '''Purpose''': Redirects incoming traffic on port 22222 to the Synology NAS

* '''Interface''': <code>ens6</code> (external/public interface)

* '''Direction''': Incoming → Forwarded

'''MASQUERADE Rule (POSTROUTING):'''
<pre class="lang-bash">
iptables -t nat -A POSTROUTING -d 10.8.0.2/32 -o tun0 -p tcp --dport 22 -j MASQUERADE
</pre>
* '''Purpose''': Handles source NAT for forwarded traffic so return packets route correctly

* '''Interface''': <code>tun0</code> (VPN tunnel)

* '''Direction''': Outgoing forwarded traffic

=== 2. iptables Filter Rules (Firewall) ===

'''FORWARD Rule:'''
<pre class="lang-bash">
iptables -t filter -A FORWARD -d 10.8.0.2/32 -p tcp --dport 22 -j ACCEPT
</pre>
* '''Purpose''': Allows forwarding packets to the Synology SSH port

* '''Direction''': Forwarded traffic

=== 3. Persistence Configuration ===

'''Files:'''
* <code>/etc/iptables/rules.v4</code> - Saved iptables rules

* <code>/etc/openvpn/server/server.conf</code> - OpenVPN configuration

* <code>/etc/openvpn/iptables-restore.sh</code> - Script that restores rules when VPN starts

* <code>/etc/sysctl.conf</code> - Contains <code>net.ipv4.ip_forward=1</code>

'''Services:'''
* <code>netfilter-persistent</code> - Loads iptables rules on boot

* <code>openvpn-server@server.service</code> - OpenVPN server service

----

== Common Issues and Solutions ==

=== Issue 1: Connection Timeout from External ===

'''Symptoms:'''
* <code>ssh -p 22222 user@87.106.61.62</code> times out

* No response from the server

'''Diagnostic Steps:'''

==== '''Check if packets are reaching the VPS:''' ====
<pre class="lang-bash">
=== Watch kernel logs for DNAT rule hits ===
=== Note: On systems using journald, kern.log may not exist. Use dmesg instead. ===
tail -f /var/log/kern.log | grep "DNAT-22222" 2>/dev/null || \
dmesg -w | grep "DNAT-22222"

=== Or check recent logs ===
dmesg | tail -30 | grep "DNAT-22222"
</pre>

== '''Check IONOS cloud firewall:''' ==
* '''IONOS Cloud Panel''': Log in to https://dcd.ionos.com/

* Navigate to: Server & Cloud → Servers → [Your VPS] → Firewall

* Verify TCP port 22222 has an '''ALLOW''' rule configured

* Check rule priority (lower numbers = higher priority)

* Ensure no DROP rules with higher priority are blocking the port

* '''This is the most common cause of timeouts on IONOS'''

* See "IONOS Cloud Provider Configuration" section above for detailed steps

== '''Verify VPN is running:''' ==
<pre class="lang-bash">
systemctl status openvpn-server@server.service
ip link show tun0
</pre>

== '''Check if Synology is connected:''' ==
<pre class="lang-bash">
ping -c 2 10.8.0.2
cat /etc/openvpn/server/ipp.txt
</pre>

'''Solution:'''
* If no logs appear: '''Check IONOS firewall in Cloud Panel''' (most common issue)

* Verify port 22222 is allowed in IONOS firewall rules

* Check rule priority and ensure no blocking rules override it

* If logs appear but connection fails: Check Synology VPN connection

* If Synology is not in ipp.txt: Reconnect Synology to VPN

----

=== Issue 2: Port Forwarding Not Working After Reboot ===

'''Symptoms:'''
* Port forwarding works initially

* After reboot, connections time out

'''Diagnostic Steps:'''

==== '''Check if iptables rules are loaded:''' ====
<pre class="lang-bash">
iptables -t nat -L PREROUTING -n -v | grep 22222
</pre>
* If rule is missing, rules weren't loaded

== '''Verify persistence services are enabled:''' ==
<pre class="lang-bash">
systemctl is-enabled netfilter-persistent
systemctl is-enabled openvpn-server@server.service
</pre>

== '''Check OpenVPN configuration:''' ==
<pre class="lang-bash">
grep "script-security\|up" /etc/openvpn/server/server.conf
</pre>
* Should show: <code>script-security 2</code> and <code>up /etc/openvpn/iptables-restore.sh</code>

== '''Verify iptables-restore script exists:''' ==
<pre class="lang-bash">
ls -la /etc/openvpn/iptables-restore.sh
cat /etc/openvpn/iptables-restore.sh
</pre>

'''Solution:'''
<pre class="lang-bash">
== Manually restore rules ==
iptables-restore < /etc/iptables/rules.v4

== Verify rules are saved correctly ==
iptables-save > /etc/iptables/rules.v4

== Ensure services are enabled ==
systemctl enable netfilter-persistent
systemctl enable openvpn-server@server.service
</pre>

----

=== Issue 3: Wrong Network Interface ===

'''Symptoms:'''
* Rules exist but forwarding doesn't work

* Interface name mismatch

'''Diagnostic Steps:'''

==== '''Identify the correct external interface:''' ====
<pre class="lang-bash">
ip route | grep default
=== Output: default via 87.106.61.1 dev ens6 ... ===
</pre>

== '''Check iptables rule interface:''' ==
<pre class="lang-bash">
iptables -t nat -L PREROUTING -n -v | grep 22222
=== Should show: -i ens6 (or your actual interface) ===
</pre>

== '''Check saved rules file:''' ==
<pre class="lang-bash">
grep "22222" /etc/iptables/rules.v4
</pre>

'''Solution:'''
<pre class="lang-bash">
== Fix the interface in the rules file ==
sed -i 's/-i eth0/-i ens6/g' /etc/iptables/rules.v4

== Or manually edit /etc/iptables/rules.v4 ==
== Change: -A PREROUTING -i eth0 ... ==
== To: -A PREROUTING -i ens6 ... ==

== Reload rules ==
iptables-restore < /etc/iptables/rules.v4
</pre>

----

=== Issue 4: SSH Conflicts with Port Forwarding ===

'''Symptoms:'''
* Port 22222 is being used by SSH

* Connection connects but to wrong server

'''Diagnostic Steps:'''

==== '''Check what's listening on port 22222:''' ====
<pre class="lang-bash">
ss -tlnp | grep 22222
</pre>

== '''Check SSH configuration:''' ==
<pre class="lang-bash">
grep "^Port" /etc/ssh/sshd_config
</pre>

'''Solution:'''
<pre class="lang-bash">
== Remove port 22222 from SSH config ==
sed -i '/^Port 22222$/d' /etc/ssh/sshd_config

== Restart SSH ==
systemctl restart sshd

== Verify port 22222 is free ==
ss -tlnp | grep 22222 # Should return nothing
</pre>

----

=== Issue 5: VPN Not Starting ===

'''Symptoms:'''
* OpenVPN service fails to start

* Error messages about script-security

'''Diagnostic Steps:'''

==== '''Check OpenVPN status:''' ====
<pre class="lang-bash">
systemctl status openvpn-server@server.service
journalctl -u openvpn-server@server.service -n 50
</pre>

== '''Common error:''' ==
<pre>
WARNING: External program may not be called unless '--script-security 2' or higher is enabled
</pre>

'''Solution:'''
<pre class="lang-bash">
== Add script-security to OpenVPN config ==
echo "script-security 2" >> /etc/openvpn/server/server.conf

== Restart OpenVPN ==
systemctl restart openvpn-server@server.service
</pre>

----

=== Issue 6: IP Forwarding Disabled ===

'''Symptoms:'''
* Rules exist but forwarding doesn't work

* Can't reach Synology even though VPN is up

'''Diagnostic Steps:'''

==== '''Check if forwarding is enabled:''' ====
<pre class="lang-bash">
cat /proc/sys/net/ipv4/ip_forward
=== Should output: 1 ===
</pre>

== '''Check if it's in sysctl.conf:''' ==
<pre class="lang-bash">
grep "ip_forward" /etc/sysctl.conf
</pre>

'''Solution:'''
<pre class="lang-bash">
== Enable forwarding ==
echo 1 > /proc/sys/net/ipv4/ip_forward

== Make it persistent ==
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf
sysctl -p
</pre>

----

== Diagnostic Commands ==

=== Check Complete Forwarding Chain ===

<pre class="lang-bash">
echo "=== Port Forwarding Status ===" && \
echo "" && \
echo "1. DNAT Rule:" && \
iptables -t nat -L PREROUTING -n -v | grep 22222 && \
echo "" && \
echo "2. FORWARD Rules:" && \
iptables -t filter -L FORWARD -n -v | grep "10.8.0.2" && \
echo "" && \
echo "3. POSTROUTING (MASQUERADE):" && \
iptables -t nat -L POSTROUTING -n -v | grep "10.8.0.2\|MASQUERADE" && \
echo "" && \
echo "4. VPN Status:" && \
ip addr show tun0 2>/dev/null | grep "inet " && \
echo "" && \
echo "5. Synology Reachability:" && \
ping -c 1 -W 2 10.8.0.2 2>&1 | grep -E "bytes from|time=" || echo "Not reachable"
</pre>

=== Monitor Connection Attempts ===

<pre class="lang-bash">
==== Watch for incoming connections ====
== Note: On systems using journald, kern.log may not exist. Use dmesg instead. ==
tail -f /var/log/kern.log | grep -E "DNAT-22222|FWD-to-Synology" 2>/dev/null || \
dmesg -w | grep -E "DNAT-22222|FWD-to-Synology"

== Or use tcpdump ==
tcpdump -i ens6 -n tcp port 22222

== Monitor iptables counters ==
watch -n 1 'iptables -t nat -L PREROUTING -n -v | grep 22222'
</pre>

=== Test Connection from VPS ===

<pre class="lang-bash">
==== Test direct connection to Synology ====
ssh -o ConnectTimeout=5 -p 22 user@10.8.0.2 "echo 'Direct connection works'"

== Test if port forwarding rule is active (from external IP) ==
timeout 5 nc -zv 87.106.61.62 22222
</pre>

----

== Restore Configuration After Issues ==

If port forwarding stops working, restore the complete configuration:

<pre class="lang-bash">
=== 1. Restore iptables rules ===
iptables-restore < /etc/iptables/rules.v4

== 2. Verify rules are loaded ==
iptables -t nat -L PREROUTING -n -v | grep 22222

== 3. Restart OpenVPN (will also restore rules via up script) ==
systemctl restart openvpn-server@server.service

== 4. Verify VPN is up ==
ip addr show tun0

== 5. Check Synology connection ==
ping -c 2 10.8.0.2
</pre>

----

== Configuration Files Reference ==

=== <code>/etc/iptables/rules.v4</code> ===
Complete iptables rules including:
* DNAT rule for port 22222

* FORWARD rule for Synology

* MASQUERADE rule for return traffic

* Logging rules for debugging

=== <code>/etc/openvpn/server/server.conf</code> ===
OpenVPN server configuration with:
* <code>script-security 2</code> - Allows up/down scripts

* <code>up /etc/openvpn/iptables-restore.sh</code> - Restores rules when VPN starts

=== <code>/etc/openvpn/iptables-restore.sh</code> ===
Script that restores iptables rules when OpenVPN tunnel comes up.

=== <code>/etc/sysctl.conf</code> ===
Contains <code>net.ipv4.ip_forward=1</code> to enable IP forwarding.

----

== Maintenance ==

=== Update Rules ===

After making changes to iptables rules:
<pre class="lang-bash">
==== Save current rules ====
iptables-save > /etc/iptables/rules.v4

== Verify they're correct ==
cat /etc/iptables/rules.v4 | grep 22222
</pre>

=== Add More Port Forwards ===

To forward additional ports:
<pre class="lang-bash">
==== Add DNAT rule ====
iptables -t nat -A PREROUTING -i ens6 -p tcp --dport <EXTERNAL_PORT> \
-j DNAT --to-destination 10.8.0.2:<INTERNAL_PORT>

== Add FORWARD rule ==
iptables -t filter -A FORWARD -d 10.8.0.2 -p tcp --dport <INTERNAL_PORT> -j ACCEPT

== Save rules ==
iptables-save > /etc/iptables/rules.v4
</pre>

----

== Quick Reference ==

{| class="wikitable"
|-
| Component || Value
|-
| External Port || 22222
|-
| Internal Target || 10.8.0.2:22
|-
| External Interface || ens6
|-
| VPN Interface || tun0
|-
| VPN Subnet || 10.8.0.0/24
|-
| VPS Public IP || 87.106.61.62
|-
| Synology VPN IP || 10.8.0.2
|-
| Cloud Provider || IONOS
|-
| IONOS Panel || https://dcd.ionos.com/
|}
== Contact & Support ==

If issues persist after following this guide:
=== Check all diagnostic commands above ===
== Review kernel logs: <code>dmesg | tail -50</code> ==
== Check OpenVPN logs: <code>journalctl -u openvpn-server@server.service -n 100</code> ==
== '''Verify IONOS firewall settings''' (most common issue): ==
* Log in to IONOS Cloud Panel: https://dcd.ionos.com/

* Navigate to Server & Cloud → Servers → [Your VPS] → Firewall

* Verify port 22222 is allowed with proper priority

== Check IONOS support documentation or contact IONOS support if firewall is correctly configured ==

[[Category:Documentation]]
[[Category:Documentation/Troubleshooting]]

Troubleshooting:Openvpn Troubleshooting

2026-01-01T13:44:48Z

Josh: Major update - troubleshooting guide: OpenVPN Troubleshooting (19 sections) (troubleshooting)

This guide covers troubleshooting for OpenVPN server and client connection issues.

== Server Not Starting ==

=== '''Check logs''': ===
<pre class="lang-bash">
journalctl -u openvpn -n 50
</pre>

== '''Verify configuration''': ==
<pre class="lang-bash">
openvpn --config /etc/openvpn/server/server.conf --test-crypto
</pre>

== '''Check file permissions''': ==
<pre class="lang-bash">
ls -la /etc/openvpn/server/
=== Certificates should be readable by OpenVPN user ===
</pre>

== Client Cannot Connect ==

=== '''Check server is listening''': ===
<pre class="lang-bash">
ss -ulnp | grep 1194
</pre>

== '''Check firewall''': ==
<pre class="lang-bash">
iptables -L INPUT -n -v | grep 1194
</pre>

== '''Verify client certificate''': ==
* Ensure certificate hasn't been revoked

* Check certificate expiration date

* Verify CA certificate matches server

== '''Check server logs''': ==
<pre class="lang-bash">
tail -f /var/log/syslog | grep openvpn
</pre>

== Connection Drops ==

=== '''Check keepalive settings''' in server.conf ===
== '''Verify network connectivity''': ==
<pre class="lang-bash">
ping 10.8.0.2
</pre>

== '''Check routing''': ==
<pre class="lang-bash">
ip route | grep 10.8.0.0
</pre>

== Performance Issues ==

=== '''Check server load''': ===
<pre class="lang-bash">
top
htop
</pre>

== '''Monitor network traffic''': ==
<pre class="lang-bash">
iftop -i tun0
</pre>

== '''Check for connection limits''' in server configuration ==

== Related Documentation ==

* [OpenVPN Server](index.md) - Server configuration

* [User Management](user-management.md) - User management

[[Category:Documentation]]
[[Category:Documentation/Troubleshooting]]

Troubleshooting:Service Troubleshooting

2026-01-01T13:44:46Z

Josh: Major update - troubleshooting guide: Service Troubleshooting (22 sections) (troubleshooting)

This guide covers troubleshooting for reverse proxy services.

== Common Issues ==

=== Issue: 502 Bad Gateway ===

'''Causes''':
* Service not running on Synology NAS

* Wrong port number

* Service not accessible via VPN

'''Solutions''':
<pre class="lang-bash">
==== Test from VPS to NAS ====
ping 10.8.0.2
curl http://10.8.0.2:PORT_NUMBER

== Check if service is listening ==
== (from Synology NAS or via SSH) ==
netstat -tlnp | grep PORT_NUMBER
</pre>

=== Issue: SSL Certificate Failed ===

'''Causes''':
* DNS not pointing to VPS

* Port 80 blocked

* Rate limiting from Let's Encrypt

'''Solutions''':
<pre class="lang-bash">
==== Check DNS ====
nslookup newservice.jb-vpn.uk

== Verify port 80 is open ==
curl -I http://newservice.jb-vpn.uk

== Check firewall ==
sudo iptables -L -n -v | grep 80
</pre>

=== Issue: Service Not Loading ===

'''Causes''':
* Wrong proxy_pass URL

* Missing headers

* Service requires specific path

'''Solutions''':
* Check nginx error log: <code>tail -f /var/log/nginx/error.log</code>

* Verify service works directly: <code>curl http://10.8.0.2:PORT</code>

* Test with different proxy_pass formats

=== Issue: Connection Timeout ===

'''Causes''':
* VPN tunnel down

* Service not accessible

* Firewall blocking

'''Solutions''':
<pre class="lang-bash">
==== Check VPN ====
ip addr show tun0
ping 10.8.0.2

== Check routing ==
ip route | grep 10.8.0.2

== Test connectivity ==
curl -v http://10.8.0.2:PORT_NUMBER
</pre>

== Diagnostic Commands ==

<pre class="lang-bash">
=== Check service status ===
systemctl status nginx

== Test nginx configuration ==
nginx -t

== View error logs ==
tail -f /var/log/nginx/error.log

== View access logs ==
tail -f /var/log/nginx/access.log

== Check SSL certificates ==
certbot certificates

== Test service directly ==
curl -I https://service.jb-vpn.uk
</pre>

== Related Documentation ==

* [Adding Services](index.md) - Service configuration

* [System Overview](index.md) - System architecture

[[Category:Documentation]]
[[Category:Documentation/Troubleshooting]]

Troubleshooting:Nginx Troubleshooting

2026-01-01T13:44:44Z

Josh: Major update - troubleshooting guide: Nginx Troubleshooting (23 sections) (troubleshooting)

This guide covers troubleshooting for Nginx configuration and service issues.

== Configuration Errors ==

=== Syntax Errors ===

'''Symptoms''': <code>nginx -t</code> fails with syntax errors

'''Solutions''':
* Check for missing semicolons

* Verify bracket matching

* Check for typos in directive names

=== Duplicate Server Names ===

'''Symptoms''': Warning about duplicate server_name

'''Solutions''':
* Check all configuration files in <code>/etc/nginx/sites-enabled/</code>

* Remove duplicate server_name entries

* Ensure only one config per subdomain

== Service Issues ==

=== Nginx Won't Start ===

==== '''Check status''': ====
<pre class="lang-bash">
systemctl status nginx
</pre>

== '''Check logs''': ==
<pre class="lang-bash">
journalctl -u nginx -n 50
</pre>

== '''Test configuration''': ==
<pre class="lang-bash">
nginx -t
</pre>

=== Nginx Reload Fails ===

==== '''Test configuration first''': ====
<pre class="lang-bash">
nginx -t
</pre>

== '''Check for syntax errors''' in configuration files ==

== '''Verify file permissions''': ==
<pre class="lang-bash">
ls -la /etc/nginx/sites-enabled/
</pre>

== Log Analysis ==

=== Error Logs ===

<pre class="lang-bash">
==== View recent errors ====
tail -f /var/log/nginx/error.log

== Search for specific errors ==
grep "error" /var/log/nginx/error.log
</pre>

=== Access Logs ===

<pre class="lang-bash">
==== View recent access ====
tail -f /var/log/nginx/access.log

== Analyze traffic ==
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn
</pre>

== Common Configuration Issues ==

=== SSL Certificate Problems ===

* Verify certificate exists: <code>certbot certificates</code>

* Check certificate expiration: <code>openssl x509 -in /etc/letsencrypt/live/domain/cert.pem -noout -dates</code>

* Renew if needed: <code>certbot renew</code>

=== Proxy Issues ===

* Check proxy_pass URL is correct

* Verify target service is accessible

* Check proxy headers are set correctly

== Related Documentation ==

* [Adding Services](index.md) - Service configuration

* [Service Management](service-management.md) - Service management

[[Category:Documentation]]
[[Category:Documentation/Troubleshooting]]

Services:Service Examples

2026-01-01T13:44:44Z

Josh: Minor update - troubleshooting guide: Service-Specific Examples (4 sections)

This document provides service-specific configuration examples.

== Basic Web Application ==

<pre class="lang-nginx">
server {
server_name app.jb-vpn.uk;

location / {
proxy_pass http://10.8.0.2:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

listen 80;
}
</pre>

== Service with API Path ==

If your service has a specific path prefix:

<pre class="lang-nginx">
server {
server_name api.jb-vpn.uk;

location / {
proxy_pass http://10.8.0.2:8080/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

listen 80;
}
</pre>

== Service Requiring Authentication Headers ==

<pre class="lang-nginx">
server {
server_name secure.jb-vpn.uk;

location / {
proxy_pass http://10.8.0.2:9000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Authorization $http_authorization;
proxy_pass_header Authorization;
}

listen 80;
}
</pre>

== Related Documentation ==

* [Step-by-Step Process](step-by-step.md) - Setup process

* [Configuration Options](configuration-options.md) - Advanced options

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Step By Step

2026-01-01T13:44:43Z

Josh: Major update - troubleshooting guide: Step-by-Step Process for Adding Services (18 sections)

Follow these steps to add a new service to the reverse proxy system.

== Step 1: Create Nginx Configuration File ==

Create a new configuration file in <code>/etc/nginx/sites-available/</code>:

<pre class="lang-bash">
sudo nano /etc/nginx/sites-available/newservice.jb-vpn.uk
</pre>

'''Basic HTTP Configuration Template''':

<pre class="lang-nginx">
server {
server_name newservice.jb-vpn.uk;

location / {
=== Reverse Proxy to Synology's internal VPN IP and service port ===
proxy_pass http://10.8.0.2:PORT_NUMBER;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
=== Necessary for Synology Reverse Proxy compatibility ===
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
=== Timeouts for long-running requests ===
proxy_read_timeout 300s;
proxy_connect_timeout 75s;
}

listen 80;

}
</pre>

'''Replace''':
* <code>newservice.jb-vpn.uk</code> with your subdomain

* <code>PORT_NUMBER</code> with your service's port

'''For HTTPS Internal Services''':

If your internal service uses HTTPS, change the proxy_pass line:
<pre class="lang-nginx">
proxy_pass https://10.8.0.2:PORT_NUMBER;
</pre>

'''For Services Requiring Special Headers''':

Some services (like Plex) require additional headers. See [Service Examples](service-examples.md) for reference.

== Step 2: Enable the Site ==

Create a symlink to enable the site:

<pre class="lang-bash">
sudo ln -s /etc/nginx/sites-available/newservice.jb-vpn.uk /etc/nginx/sites-enabled/newservice.jb-vpn.uk
</pre>

== Step 3: Test Nginx Configuration ==

Always test the configuration before reloading:

<pre class="lang-bash">
sudo nginx -t
</pre>

'''Expected Output''':
<pre>
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
</pre>

'''If there are errors''': Fix them before proceeding. Common issues:
* Syntax errors (missing semicolons, brackets)

* Duplicate server names

* Invalid port numbers

== Step 4: Reload Nginx ==

Reload nginx to apply the new configuration (graceful reload, no downtime):

<pre class="lang-bash">
sudo systemctl reload nginx
</pre>

== Step 5: Verify HTTP Access ==

Test that the service is accessible via HTTP:

<pre class="lang-bash">
curl -I http://newservice.jb-vpn.uk
</pre>

You should receive an HTTP response. If you get a connection error:
* Check DNS: <code>nslookup newservice.jb-vpn.uk</code>

* Verify service is running: <code>curl http://10.8.0.2:PORT_NUMBER</code>

* Check nginx logs: <code>tail -f /var/log/nginx/error.log</code>

== Step 6: Set Up SSL Certificate ==

Use Certbot to automatically configure SSL:

<pre class="lang-bash">
sudo certbot --nginx -d newservice.jb-vpn.uk --non-interactive --agree-tos --redirect --email admin@jb-vpn.uk
</pre>

'''What this does''':
* Requests SSL certificate from Let's Encrypt

* Configures nginx for HTTPS

* Sets up HTTP to HTTPS redirect

* Configures automatic renewal

'''If Certbot fails''':
* Verify DNS is pointing to VPS: <code>nslookup newservice.jb-vpn.uk</code>

* Ensure port 80 is open and accessible

* Check firewall rules: <code>sudo iptables -L -n -v</code>

== Step 7: Verify HTTPS Access ==

Test that HTTPS is working:

<pre class="lang-bash">
curl -I https://newservice.jb-vpn.uk
</pre>

You should receive a 200 OK or similar response with SSL certificate details.

== Step 8: Test in Browser ==

Open your browser and navigate to:
<pre>
https://newservice.jb-vpn.uk
</pre>

Verify:
* SSL certificate is valid (green lock icon)

* Service loads correctly

* All functionality works as expected

== Removing a Service ==

To remove a service:

=== '''Disable the site''': ===
<pre class="lang-bash">
sudo rm /etc/nginx/sites-enabled/service.jb-vpn.uk
</pre>

== '''Test configuration''': ==
<pre class="lang-bash">
sudo nginx -t
</pre>

== '''Reload nginx''': ==
<pre class="lang-bash">
sudo systemctl reload nginx
</pre>

== '''Optional - Remove configuration file''': ==
<pre class="lang-bash">
sudo rm /etc/nginx/sites-available/service.jb-vpn.uk
</pre>

== '''Optional - Revoke SSL certificate''': ==
<pre class="lang-bash">
sudo certbot revoke --cert-path /etc/letsencrypt/live/service.jb-vpn.uk/cert.pem
sudo certbot delete --cert-name service.jb-vpn.uk
</pre>

== Related Documentation ==

* [[Documentation:Prerequisites](Prerequisites|- Requirements before starting

* [Configuration Options]])(configuration-options.md) - Advanced configuration

* [Service Examples](service-examples.md) - Service-specific examples

* [[Documentation:Index|Troubleshooting]] - Common issues

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Prerequisites

2026-01-01T13:44:42Z

Josh: Major update - troubleshooting guide: Prerequisites for Adding Services (27 sections)

Before adding a new service to the reverse proxy system, ensure you have the following:

== Service Information ==

=== '''Subdomain name''' (e.g., <code>newservice.jb-vpn.uk</code>) ===
== '''Internal IP address''' (usually <code>10.8.0.2</code> for Synology NAS) ==
== '''Internal port number''' (e.g., <code>8080</code>, <code>3000</code>, etc.) ==
== '''Protocol''' (HTTP or HTTPS) ==

== DNS Configuration ==

=== '''DNS A record created''' pointing subdomain to VPS IP (<code>87.106.61.62</code>) ===
== '''DNS propagation completed''' (can take up to 48 hours, usually much faster) ==

=== Verify DNS Configuration ===

<pre class="lang-bash">
==== Check DNS resolution ====
nslookup newservice.jb-vpn.uk

== Or using dig ==
dig newservice.jb-vpn.uk +short
</pre>

== Service Verification ==

Before configuring the reverse proxy, verify:

=== '''Service is running''' on Synology NAS ===
== '''Service is accessible''' from VPN network ==
== '''Test from VPS''': <code>curl http://10.8.0.2:[PORT]</code> ### Test Service Accessibility ==

<pre class="lang-bash">
== Test service from VPS ==
curl http://10.8.0.2:8080

== Check if service is listening (from Synology NAS or via SSH) ==
netstat -tlnp | grep PORT_NUMBER
</pre>

== System Requirements ==

Ensure the following are in place:

=== '''OpenVPN tunnel is active''' (tun0 interface up) ===
== '''Synology NAS is connected''' to VPN (10.8.0.2 reachable) ==
== '''Nginx is running''' on the VPS ==
== '''Port 80 is accessible''' (required for SSL certificate validation) ==

=== Verify System Status ===

<pre class="lang-bash">
==== Check VPN connectivity ====
ping 10.8.0.2

== Check nginx status ==
systemctl status nginx

== Check VPN interface ==
ip addr show tun0
</pre>

== Related Documentation ==

* [Step-by-Step Process](step-by-step.md) - Next steps after prerequisites

* [System Overview](index.md) - System architecture

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Best Practices

2026-01-01T13:44:41Z

Josh: Content added - troubleshooting guide: Best Practices for Adding Services (11 sections)

This document outlines best practices when adding new services to the reverse proxy system.

== General Best Practices ==

=== '''Always test configuration''' before reloading nginx ===
== '''Use descriptive subdomain names''' that indicate the service ==
== '''Document your services''' in [Current Services](current-services.md) ==
== '''Backup configurations''' before making changes ==
== '''Monitor logs''' after adding new services ==
== '''Use HTTPS''' for all public-facing services ==
== '''Test thoroughly''' before marking service as complete ==

== Checklist ==

Use this checklist when adding a new service:

* [ ] DNS A record created and propagated

* [ ] Service running on Synology NAS

* [ ] Service accessible from VPN network

* [ ] Nginx configuration file created

* [ ] Site enabled (symlink created)

* [ ] Nginx configuration tested (<code>nginx -t</code>)

* [ ] Nginx reloaded

* [ ] HTTP access verified

* [ ] SSL certificate obtained

* [ ] HTTPS access verified

* [ ] Browser testing completed

* [ ] Service documented in [Current Services](current-services.md)

== Security Considerations ==

* Always use HTTPS for public-facing services

* Keep SSL certificates up to date (automatic renewal via Certbot)

* Use strong authentication for services that require it

* Monitor access logs for unusual activity

== Related Documentation ==

* [Step-by-Step Process](step-by-step.md) - Setup process

* [[Documentation:Index|Troubleshooting]] - Common issues

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Configuration Options

2026-01-01T13:44:40Z

Josh: Minor update - configuration guide: Configuration Options (6 sections) (configuration)

This document describes advanced configuration options for services.

== Custom Timeouts ==

For services that need longer timeouts:

<pre class="lang-nginx">
proxy_read_timeout 600s; # 10 minutes
proxy_connect_timeout 75s;
proxy_send_timeout 600s;
</pre>

== WebSocket Support ==

For WebSocket applications (already included in template):

<pre class="lang-nginx">
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
</pre>

== Custom Headers ==

Some services require specific headers. Add them in the location block:

<pre class="lang-nginx">
proxy_set_header X-Custom-Header "value";
proxy_set_header Authorization $http_authorization;
</pre>

== Buffer Settings ==

For large file uploads or downloads:

<pre class="lang-nginx">
client_max_body_size 100M;
proxy_buffering off;
</pre>

== Bypass SSL Verification (Internal HTTPS) ==

If your internal service uses self-signed certificates:

<pre class="lang-nginx">
proxy_ssl_verify off;
proxy_ssl_trusted_certificate /path/to/ca.crt;
</pre>

'''Warning''': Only use this for internal services, never for external connections.

== Related Documentation ==

* [Step-by-Step Process](step-by-step.md) - Basic setup

* [Service Examples](service-examples.md) - Example configurations

[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]

Services:Current Services

2026-01-01T13:44:39Z

Josh: Major update - troubleshooting guide: Current Services - Service Inventory (32 sections)

This document provides a detailed inventory of all services currently configured on the reverse proxy system.

== Service Summary ==

{| class="wikitable"
|-
| Service || Subdomain || Internal Port || Protocol || Status || SSL
|-
| Wiki || wiki.jb-vpn.uk || 8080 || HTTP || Active || ✅
|-
| Werbs-Wiki || werbs-wiki.jb-vpn.uk || 8081 || HTTP || Active || ✅
|-
| Synology DSM || dsm.jb-vpn.uk || 5001 || HTTPS || Active || ✅
|-
| Plex Media Server || plex.jb-vpn.uk || 32400 || HTTP || Active || ✅
|-
| VPS Default || vps.jb-vpn.uk || - || - || Active || ✅
|}
== Service Details ==

=== 1. Wiki Service ===

'''Subdomain''': <code>wiki.jb-vpn.uk</code>

'''Public Access''': <code>https://wiki.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Target IP''': <code>10.8.0.2</code> (Synology NAS via VPN)

* '''Target Port''': <code>8080</code>

* '''Protocol''': HTTP

'''Nginx Configuration''':
* '''File''': <code>/etc/nginx/sites-available/wiki.jb-vpn.uk</code>

* '''Enabled''': <code>/etc/nginx/sites-enabled/wiki.jb-vpn.uk</code>

'''SSL Certificate''':
* '''Provider''': Let's Encrypt

* '''Certificate Path''': <code>/etc/letsencrypt/live/wiki.jb-vpn.uk/</code>

* '''Expiry Date''': 2026-02-01

* '''Status''': Valid (89 days remaining)

'''Traffic Flow''':
<pre>
External Request → wiki.jb-vpn.uk:443 (HTTPS)
→ Nginx Reverse Proxy (SSL Termination)
→ 10.8.0.2:8080 (HTTP on Synology NAS)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* WebSocket support: ✅ Enabled

* Extended timeouts: ✅ 300 seconds

* Proxy headers: ✅ Full set configured

'''DNS Record''': <code>wiki.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://wiki.jb-vpn.uk
== Or access directly: https://wiki.jb-vpn.uk/index.php?title=Main_Page ==
</pre>

----

=== 2. Werbs-Wiki Service ===

'''Subdomain''': <code>werbs-wiki.jb-vpn.uk</code>

'''Public Access''': <code>https://werbs-wiki.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Target IP''': <code>10.8.0.2</code> (Synology NAS via VPN)

* '''Target Port''': <code>8081</code>

* '''Protocol''': HTTP

'''Nginx Configuration''':
* '''File''': <code>/etc/nginx/sites-available/werbs-wiki.jb-vpn.uk</code>

* '''Enabled''': <code>/etc/nginx/sites-enabled/werbs-wiki.jb-vpn.uk</code>

'''SSL Certificate''':
* '''Provider''': Let's Encrypt

* '''Certificate Path''': <code>/etc/letsencrypt/live/werbs-wiki.jb-vpn.uk/</code>

* '''Expiry Date''': 2026-02-01

* '''Status''': Valid (89 days remaining)

'''Traffic Flow''':
<pre>
External Request → werbs-wiki.jb-vpn.uk:443 (HTTPS)
→ Nginx Reverse Proxy (SSL Termination)
→ 10.8.0.2:8081 (HTTP on Synology NAS)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* WebSocket support: ✅ Enabled

* Extended timeouts: ✅ 300 seconds

* Proxy headers: ✅ Full set configured

'''DNS Record''': <code>werbs-wiki.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://werbs-wiki.jb-vpn.uk
</pre>

----

=== 3. Synology DSM ===

'''Subdomain''': <code>dsm.jb-vpn.uk</code>

'''Public Access''': <code>https://dsm.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Target IP''': <code>10.8.0.2</code> (Synology NAS via VPN)

* '''Target Port''': <code>5001</code>

* '''Protocol''': HTTPS

'''Nginx Configuration''':
* '''File''': <code>/etc/nginx/sites-available/dsm.jb-vpn.uk</code>

* '''Enabled''': <code>/etc/nginx/sites-enabled/dsm.jb-vpn.uk</code>

'''SSL Certificate''':
* '''Provider''': Let's Encrypt

* '''Certificate Path''': <code>/etc/letsencrypt/live/vps.jb-vpn.uk/</code> (shared certificate)

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → dsm.jb-vpn.uk:443 (HTTPS)
→ Nginx Reverse Proxy (SSL Termination)
→ 10.8.0.2:5001 (HTTPS on Synology NAS)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* WebSocket support: ✅ Enabled (for DSM WebSocket features)

* Internal HTTPS: ✅ Passes through to Synology HTTPS

'''DNS Record''': <code>dsm.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://dsm.jb-vpn.uk
</pre>

----

=== 4. Plex Media Server ===

'''Subdomain''': <code>plex.jb-vpn.uk</code>

'''Public Access''': <code>https://plex.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Target IP''': <code>10.8.0.2</code> (Synology NAS via VPN)

* '''Target Port''': <code>32400</code>

* '''Protocol''': HTTP

'''Nginx Configuration''':
* '''File''': <code>/etc/nginx/sites-available/plex.jb-vpn.uk</code>

* '''Enabled''': <code>/etc/nginx/sites-enabled/plex.jb-vpn.uk</code>

'''SSL Certificate''':
* '''Provider''': Let's Encrypt

* '''Certificate Path''': <code>/etc/letsencrypt/live/vps.jb-vpn.uk/</code> (shared certificate)

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → plex.jb-vpn.uk:443 (HTTPS)
→ Nginx Reverse Proxy (SSL Termination)
→ 10.8.0.2:32400 (HTTP on Synology NAS)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* Plex-specific headers: ✅ Configured

* X-Plex-Client-Identifier

* X-Plex-Device

* X-Plex-Product

* X-Plex-Version

* X-Plex-Platform

* X-Plex-Platform-Version

* X-Plex-Device-Name

* X-Plex-Provides

* X-Plex-Token

'''DNS Record''': <code>plex.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://plex.jb-vpn.uk
</pre>

----

=== 5. VPS Default Web Directory ===

'''Subdomain''': <code>vps.jb-vpn.uk</code>

'''Public Access''': <code>https://vps.jb-vpn.uk</code>

'''Internal Configuration''':
* '''Type''': Static files

* '''Web Root''': <code>/var/www/html</code>

* '''Protocol''': Direct file serving

'''Nginx Configuration''':
* '''File''': <code>/etc/nginx/sites-available/vps.jb-vpn.uk</code>

* '''Enabled''': <code>/etc/nginx/sites-enabled/vps.jb-vpn.uk</code>

'''SSL Certificate''':
* '''Provider''': Let's Encrypt

* '''Certificate Path''': <code>/etc/letsencrypt/live/vps.jb-vpn.uk/</code>

* '''Status''': Valid

'''Traffic Flow''':
<pre>
External Request → vps.jb-vpn.uk:443 (HTTPS)
→ Nginx (SSL Termination)
→ /var/www/html (Local file serving)
</pre>

'''Configuration Details''':
* HTTP to HTTPS redirect: ✅ Enabled

* Static file serving: ✅ Enabled

* Index files: <code>index.html</code>, <code>index.htm</code>, <code>index.nginx-debian.html</code>

'''DNS Record''': <code>vps.jb-vpn.uk</code> → <code>87.106.61.62</code>

'''Test Command''':
<pre class="lang-bash">
curl -I https://vps.jb-vpn.uk
</pre>

----

== Additional Services (Non-Web) ==

=== SSH Port Forwarding ===

SSH port forwarding is managed through a centralized configuration system. See [SSH Port Forwarding Management](index.md) for complete documentation.

'''Current Forwards''':
* '''Synology NAS''': Port <code>22222</code> → <code>10.8.0.2:22</code>

* Access: <code>ssh -p 22222 user@87.106.61.62</code>

'''Management''':
<pre class="lang-bash">
== List all SSH port forwards ==
sudo ssh-forward list

== Add a new device ==
sudo ssh-forward add <name> <external_port> <vpn_ip> [ssh_port]

== Remove a device ==
sudo ssh-forward remove <name>
</pre>

'''Configuration File''': <code>/etc/ssh-port-forwards.conf</code>

'''Note''': This is a direct port forward via iptables, not handled by nginx.

----

== Service Status Monitoring ==

=== Check All Services ===

<pre class="lang-bash">
==== Test all HTTPS services ====
for domain in wiki.jb-vpn.uk werbs-wiki.jb-vpn.uk dsm.jb-vpn.uk plex.jb-vpn.uk vps.jb-vpn.uk; do
echo "Testing $domain..."
curl -I -s https://$domain | head -1
done
</pre>

=== Check SSL Certificates ===

<pre class="lang-bash">
certbot certificates
</pre>

=== Check Nginx Status ===

<pre class="lang-bash">
systemctl status nginx
</pre>

=== View Active Sites ===

<pre class="lang-bash">
ls -la /etc/nginx/sites-enabled/
</pre>

----

== Service Dependencies ==

=== Required for All Services ===

==== '''OpenVPN Tunnel''': Must be active (tun0 interface up) ====
== '''Synology NAS''': Must be connected to VPN (10.8.0.2 reachable) ==
== '''Nginx Service''': Must be running ==
== '''DNS Records''': Must point to VPS IP (87.106.61.62) ==

=== Service-Specific Requirements ===

* '''Wiki/Werbs-Wiki''': Services must be running on ports 8080/8081

* '''DSM''': Synology DSM must be enabled

* '''Plex''': Plex Media Server must be running

* '''VPS Default''': No dependencies (local files only)

----

== Maintenance Schedule ==

=== Daily ===
* Monitor nginx error logs

* Check service availability

=== Weekly ===
* Review access logs for anomalies

* Verify SSL certificate status

=== Monthly ===
* Backup nginx configurations

* Review and update documentation

* Check for service updates

=== Quarterly ===
* Verify SSL certificate auto-renewal

* Review firewall rules

* Update system packages

----

== Service Statistics ==

'''Total Services''': 5 web services + 1 SSH port forward

'''SSL Certificates''': 3 unique certificates (some shared)

'''Configuration Files''': 5 nginx site configurations

'''Internal Ports Used''': 8080, 8081, 5001, 32400, 22

----

[[Category:Documentation]]
[[Category:Documentation/Services]]

SSH Port Forwarding:Overview

2026-01-01T13:44:39Z

Josh: Content added - troubleshooting guide: SSH Port Forwarding Overview (10 sections)

This document describes the SSH port forwarding system architecture and how it works.

== Architecture ==

=== Components ===

==== '''Configuration File''': <code>/etc/ssh-port-forwards.conf</code> ====
* Defines all SSH port forwards in a simple format

* One device per line

== '''Management Script''': <code>/usr/local/bin/ssh-port-forward-manager.sh</code> ==
* Adds, removes, and lists SSH port forwards

* Applies iptables rules automatically

* Validates configurations

== '''Integration''': <code>/etc/openvpn/iptables-restore.sh</code> ==
* Automatically applies all port forwards when VPN starts

* Ensures rules persist after reboots

=== How It Works ===

<pre>
External Client → VPS:EXTERNAL_PORT (e.g., 22222)
→ iptables DNAT rule
→ VPN Tunnel (tun0)
→ VPN_DEVICE:SSH_PORT (e.g., 10.8.0.2:22)
</pre>

== Current Configuration ==

To see the current configuration:

<pre class="lang-bash">
cat /etc/ssh-port-forwards.conf
</pre>

To see active iptables rules:

<pre class="lang-bash">
== View DNAT rules ==
iptables -t nat -L PREROUTING -n -v | grep DNAT

== View FORWARD rules ==
iptables -t filter -L FORWARD -n -v | grep -E "10\.8\.0\."
</pre>

== Related Documentation ==

* [[Documentation:Configuration](Configuration|- Configuration file format

* [Management]])(management.md) - Managing port forwards

* [[Troubleshooting:Port Forwarding Troubleshooting|Troubleshooting]] - Troubleshooting guide

[[Category:Documentation]]
[[Category:Documentation/SSH Port Forwarding]]

SSH Port Forwarding:Best Practices

2026-01-01T13:44:38Z

Josh: Content added - troubleshooting guide: Best Practices for Adding Services (11 sections)

SSH Port Forwarding:Management

2026-01-01T13:44:36Z

Josh: Major update - troubleshooting guide: SSH Port Forwarding Management (32 sections)

This document describes how to manage SSH port forwards.

== Management Script Usage ==

The management script is available at <code>/usr/local/bin/ssh-port-forward-manager.sh</code> or via the alias <code>ssh-forward</code>.

=== List All Port Forwards ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh list
==== or ====
sudo ssh-forward list
</pre>

This displays all configured port forwards with their status (Active/Inactive).

=== Add a New Port Forward ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh add <name> <external_port> <vpn_ip> [ssh_port]
</pre>

'''Example:'''
<pre class="lang-bash">
==== Add SSH forward for a Raspberry Pi at 10.8.0.3 on external port 22223 ====
sudo ssh-forward add raspberrypi 22223 10.8.0.3 22

== Add SSH forward for a server using non-standard SSH port ==
sudo ssh-forward add server 22224 10.8.0.4 2222
</pre>

'''Parameters:'''
* <code>name</code>: Unique name for the device

* <code>external_port</code>: Port on VPS (must not be in use)

* <code>vpn_ip</code>: Device's VPN IP address

* <code>ssh_port</code>: SSH port on device (optional, defaults to 22)

=== Remove a Port Forward ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh remove <name>
</pre>

'''Example:'''
<pre class="lang-bash">
sudo ssh-forward remove raspberrypi
</pre>

This removes the port forward from both the configuration file and iptables rules.

=== Apply All Port Forwards ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh apply
</pre>

This reads the configuration file and applies all port forwards. Useful after:
* Manual edits to the configuration file

* System reboot (automatically done by iptables-restore.sh)

* VPN restart

=== Save Current Rules ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh save
</pre>

Saves current iptables rules to <code>/etc/iptables/rules.v4</code> for persistence.

== Adding a New Device ==

=== Prerequisites ===

==== '''Device must be connected to OpenVPN VPN''' ====
* Device should have a <code>.ovpn</code> configuration file

* Device should be connected and have a VPN IP address

* Verify connection: <code>ping <VPN_IP></code> from VPS

== '''Device must have SSH enabled''' ==
* SSH service should be running on the device

* SSH should be accessible from the VPN network

== '''Choose an external port''' ==
* Must not conflict with existing services

* Recommended range: 22222-22299 for SSH forwards

* Check availability: <code>sudo ssh-forward list</code>

=== Step-by-Step Guide ===

==== '''Verify device is on VPN:''' ====
<pre class="lang-bash">
=== Check VPN connection ===
cat /etc/openvpn/server/ipp.txt | grep <device_name>

=== Ping device ===
ping -c 2 <VPN_IP>
</pre>

== '''Test direct SSH connection:''' ==
<pre class="lang-bash">
=== From VPS, test SSH to device via VPN ===
ssh -o ConnectTimeout=5 user@<VPN_IP>
</pre>

== '''Add the port forward:''' ==
<pre class="lang-bash">
sudo ssh-forward add <device_name> <external_port> <VPN_IP> [ssh_port]
</pre>

== '''Verify the forward:''' ==
<pre class="lang-bash">
=== List all forwards ===
sudo ssh-forward list

=== Test from external location ===
ssh -p <external_port> user@<VPS_PUBLIC_IP>
</pre>

== '''Configure IONOS firewall (if applicable):''' ==
* Log in to IONOS Cloud Panel: https://dcd.ionos.com/

* Navigate to: Server & Cloud → Servers → [Your VPS] → Firewall

* Add rule: TCP port <code><external_port></code> → Allow

* Set appropriate priority

=== Example: Adding a Raspberry Pi ===

<pre class="lang-bash">
==== 1. Verify Raspberry Pi is on VPN (assume it gets 10.8.0.3) ====
ping -c 2 10.8.0.3

== 2. Test direct SSH (using root for Cursor compatibility) ==
ssh root@10.8.0.3

== 3. Add port forward ==
sudo ssh-forward add raspberrypi 22223 10.8.0.3 22

== 4. Verify ==
sudo ssh-forward list

== 5. Test from external location ==
ssh -p 22223 root@87.106.61.62
</pre>

== Related Documentation ==

* [[Documentation:Overview](Overview|- System architecture

* [Configuration]])(configuration.md) - Configuration file format

* [Best Practices](best-practices.md) - Security and best practices

* [[Troubleshooting:Port Forwarding Troubleshooting|Troubleshooting]] - Troubleshooting guide

[[Category:Documentation]]
[[Category:Documentation/SSH Port Forwarding]]

SSH Port Forwarding:Configuration

2026-01-01T13:44:35Z

Josh: Content added - configuration guide: SSH Port Forwarding Configuration (8 sections) (configuration)

This document describes the configuration file format for SSH port forwarding.

== Configuration File Format ==

The configuration file <code>/etc/ssh-port-forwards.conf</code> uses a simple format:

<pre>
DEVICE_NAME:EXTERNAL_PORT:VPN_IP:SSH_PORT
</pre>

=== Example ===

<pre>
synology:22222:10.8.0.2:22
raspberrypi:22223:10.8.0.3:22
server:22224:10.8.0.4:22
</pre>

=== Fields ===

* '''DEVICE_NAME''': A descriptive name for the device (e.g., <code>synology</code>, <code>raspberrypi</code>)

* '''EXTERNAL_PORT''': The port on the VPS that will receive SSH connections (e.g., <code>22222</code>)

* '''VPN_IP''': The IP address of the device on the VPN network (e.g., <code>10.8.0.2</code>)

* '''SSH_PORT''': The SSH port on the target device (default: <code>22</code>)

=== Comments ===

Lines starting with <code>#</code> are treated as comments and ignored.

== Manual Configuration File Editing ==

You can manually edit <code>/etc/ssh-port-forwards.conf</code> and then apply:

<pre class="lang-bash">
=== Edit config file ===
sudo nano /etc/ssh-port-forwards.conf

== Apply changes ==
sudo ssh-forward apply
</pre>

== Related Documentation ==

* [[Documentation:Overview](Overview|- System architecture

* [Management]])(management.md) - Managing port forwards

[[Category:Documentation]]
[[Category:Documentation/SSH Port Forwarding]]

SSH Port Forwarding:Quickstart

2026-01-01T13:44:33Z

Josh: Major update - troubleshooting guide: SSH Port Forwarding - Quick Start Guide (25 sections)

== What Changed? ==

The SSH port forwarding system has been refactored from hardcoded iptables rules to a flexible, configuration-driven system. This makes it easy to add SSH access to multiple devices on your VPN.

=== Before ===
* Hardcoded iptables rules in <code>/etc/iptables/rules.v4</code>

* Manual rule management

* Difficult to add new devices

=== After ===
* Configuration file: <code>/etc/ssh-port-forwards.conf</code>

* Management script: <code>ssh-forward</code> (or <code>ssh-port-forward-manager.sh</code>)

* Easy to add/remove devices

* Automatic rule application

== Your Existing Setup ==

Your Synology NAS SSH forward has been migrated automatically:
* '''Device''': synology

* '''External Port''': 22222

* '''VPN IP''': 10.8.0.2

* '''SSH Port''': 22

* '''Access''': <code>ssh -p 22222 user@87.106.61.62</code>

'''No changes needed''' - everything continues to work as before!

== Adding a New Device ==

=== Example: Add a Raspberry Pi ===

==== '''Verify the device is on VPN:''' ====
<pre class="lang-bash">
=== Check if device is connected ===
cat /etc/openvpn/server/ipp.txt
ping -c 2 10.8.0.3 # Replace with your device's VPN IP
</pre>

== '''Add the port forward:''' ==
<pre class="lang-bash">
sudo ssh-forward add raspberrypi 22223 10.8.0.3 22
</pre>

== '''Verify it's active:''' ==
<pre class="lang-bash">
sudo ssh-forward list
</pre>

== '''Test from external location:''' ==
<pre class="lang-bash">
ssh -p 22223 user@87.106.61.62
</pre>

== '''Configure IONOS firewall:''' ==
* Log in to https://dcd.ionos.com/

* Navigate to: Server & Cloud → Servers → [Your VPS] → Firewall

* Add rule: TCP port <code>22223</code> → Allow

== Common Commands ==

<pre class="lang-bash">
=== List all SSH port forwards ===
sudo ssh-forward list

== Add a new device ==
sudo ssh-forward add <name> <external_port> <vpn_ip> [ssh_port] # Remove a device
sudo ssh-forward remove <name>

== Reapply all forwards (after manual config edit) ==
sudo ssh-forward apply
</pre>

== Port Recommendations ==

* '''22222-22299''': Reserved for SSH port forwards

* '''22222''': Synology NAS (already in use)

* '''22223+''': Available for new devices

== Configuration File ==

Location: <code>/etc/ssh-port-forwards.conf</code>

Format:
<pre>
device_name:external_port:vpn_ip:ssh_port
</pre>

Example:
<pre>
synology:22222:10.8.0.2:22
raspberrypi:22223:10.8.0.3:22
</pre>

== Troubleshooting ==

=== Port forward not working? ===

==== Check device is on VPN: ====
<pre class="lang-bash">
ping -c 2 <vpn_ip>
</pre>

== Verify rules exist: ==
<pre class="lang-bash">
sudo ssh-forward list
iptables -t nat -L PREROUTING -n | grep <external_port>
</pre>

== Reapply rules: ==
<pre class="lang-bash">
sudo ssh-forward apply
</pre>

== Check IONOS firewall allows the port ==

=== Need more help? ===

See the complete documentation: [SSH Port Forwarding Management](index.md)

----

'''Quick Reference''': <code>ssh-forward</code> or <code>/usr/local/bin/ssh-port-forward-manager.sh</code>

[[Category:Documentation]]
[[Category:Documentation/SSH Port Forwarding]]

System:DNS Requirements

2026-01-01T13:44:32Z

Josh: Content added - troubleshooting guide: DNS Requirements (11 sections)

This document describes DNS configuration requirements for the reverse proxy system.

== DNS Configuration ==

For the system to work, each subdomain must have a DNS A record pointing to the VPS:

<pre>
[subdomain].jb-vpn.uk → 87.106.61.62
</pre>

=== Examples ===

* <code>wiki.jb-vpn.uk</code> → <code>87.106.61.62</code>

* <code>werbs-wiki.jb-vpn.uk</code> → <code>87.106.61.62</code>

* <code>dsm.jb-vpn.uk</code> → <code>87.106.61.62</code>

* <code>plex.jb-vpn.uk</code> → <code>87.106.61.62</code>

== DNS Propagation ==

DNS changes can take up to 48 hours to propagate, though typically much faster.

=== Verify DNS Configuration ===

<pre class="lang-bash">
==== Check DNS resolution ====
nslookup wiki.jb-vpn.uk

== Or using dig ==
dig wiki.jb-vpn.uk +short
</pre>

== SSL Certificate Requirements ==

Before obtaining an SSL certificate, ensure:

=== DNS A record is created ===
== DNS has propagated (can be verified with <code>nslookup</code>) ==
== Port 80 is accessible (required for Let's Encrypt validation) ==

== Related Documentation ==

* [Network Architecture](network-architecture.md) - Network overview

* [Adding Services](index.md) - Service configuration

[[Category:Documentation]]
[[Category:Documentation/System]]

System:Network Architecture

2026-01-01T13:44:31Z

Josh: Content added - troubleshooting guide: Network Architecture (15 sections)

This document describes the network architecture of the reverse proxy system.

== Network Topology ==

<pre>
Internet → VPS (87.106.61.62) → OpenVPN Tunnel (tun0) → Synology NAS (10.8.0.2)
</pre>

== Network Components ==

* '''VPS Public IP''': 87.106.61.62

* '''VPN Network''': 10.8.0.0/24

* '''VPN Interface''': tun0 (10.8.0.1)

* '''Synology NAS IP''': 10.8.0.2 (via VPN)

* '''Web Server''': Nginx (reverse proxy)

* '''SSL Certificates''': Let's Encrypt (managed by Certbot)

== Traffic Flow ==

=== '''Client Request''': User accesses a subdomain (e.g., <code>wiki.jb-vpn.uk</code>) ===
== '''DNS Resolution''': DNS resolves to VPS public IP (87.106.61.62) ==
== '''Nginx Receives''': Nginx listens on ports 80 (HTTP) and 443 (HTTPS) ==
== '''SSL Termination''': If HTTPS, SSL is terminated at the VPS ==
== '''Reverse Proxy''': Nginx forwards the request through the VPN tunnel to the Synology NAS ==
== '''Service Response''': Synology service responds back through the tunnel ==
== '''Client Response''': Nginx sends the response back to the client ==

== Network Diagram ==

<pre>
┌─────────────┐
│ Client │
│ (Browser) │
└──────┬──────┘
│ HTTPS (443)
│
▼
┌─────────────────────────────────────┐
│ VPS (87.106.61.62) │
│ ┌───────────────────────────────┐ │
│ │ Nginx (Reverse Proxy) │ │
│ │ - SSL Termination │ │
│ │ - Request Routing │ │
│ │ - Header Rewriting │ │
│ └───────────┬───────────────────┘ │
│ │ │
│ │ OpenVPN Tunnel │
│ │ (tun0: 10.8.0.1) │
└──────────────┼───────────────────────┘
│
│ HTTP (Internal)
▼
┌─────────────────────────────────────┐
│ Synology NAS (10.8.0.2) │
│ ┌───────────────────────────────┐ │
│ │ Internal Services │ │
│ │ - Port 8080 (Wiki) │ │
│ │ - Port 8081 (Werbs-Wiki) │ │
│ │ - Port 5001 (DSM) │ │
│ │ - Port 32400 (Plex) │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘
</pre>

== Network Ports ==

=== Public Ports (VPS) ===

* '''Port 80 (HTTP)''': Redirects to HTTPS

* '''Port 443 (HTTPS)''': SSL/TLS encrypted traffic

* '''Port 22 (SSH)''': Server administration

* '''Port 1194 (UDP)''': OpenVPN server

=== Internal Ports (Synology NAS via VPN) ===

* '''Port 8080''': Wiki service

* '''Port 8081''': Werbs-Wiki service

* '''Port 5001''': Synology DSM

* '''Port 32400''': Plex Media Server

* '''Port 22''': SSH (forwarded via iptables on port 22222)

== Related Documentation ==

* [Key Components](components.md) - Detailed component information

* [OpenVPN Server](index.md) - VPN configuration

* [[Documentation:Index|Troubleshooting]] - Network troubleshooting

[[Category:Documentation]]
[[Category:Documentation/System]]

System:Components

2026-01-01T13:44:31Z

Josh: Minor update - configuration guide: Key Components (6 sections)

This document describes the key components of the reverse proxy system.

== Nginx Reverse Proxy ==

'''Purpose''': Acts as the entry point for all web traffic, handling SSL termination and request forwarding.

'''Configuration Locations''':
* '''Available Configs''': <code>/etc/nginx/sites-available/</code>

* '''Enabled Configs''': <code>/etc/nginx/sites-enabled/</code> (symlinks to sites-available)

'''Key Features''':
* SSL/TLS termination

* HTTP to HTTPS redirects

* Proxy header forwarding

* WebSocket support

* Request routing based on hostname

=== Proxy Headers ===

Nginx forwards important headers to maintain client information:

* '''Host''': Preserves the original host header

* '''X-Real-IP''': Client's real IP address

* '''X-Forwarded-For''': Forwarded for chain (for multi-proxy scenarios)

* '''X-Forwarded-Proto''': Original protocol (http/https)

* '''Upgrade & Connection''': For WebSocket support

== SSL/TLS Certificates ==

'''Provider''': Let's Encrypt (free SSL certificates)

'''Management''': Certbot (automatic renewal every 90 days)

'''Certificate Storage''': <code>/etc/letsencrypt/live/[domain]/</code> '''Features''':
* Automatic renewal via cron/systemd timer

* Wildcard or single-domain certificates

* HTTPS enforcement (HTTP redirects to HTTPS)

== OpenVPN Tunnel ==

'''Purpose''': Creates a secure, encrypted tunnel between the VPS and Synology NAS.

'''Network Details''':
* VPN Server: VPS (10.8.0.1)

* VPN Client: Synology NAS (10.8.0.2)

* Network Range: 10.8.0.0/24

'''Security''':
* Encrypted traffic between VPS and NAS

* NAS not directly exposed to internet

* Internal services accessible only via VPN

== Firewall and Routing ==

'''iptables Rules''':
* '''NAT Rules''': Port forwarding for direct TCP connections

* '''MASQUERADE''': Enables VPN clients to access internet through VPS

* '''FORWARD Rules''': Controls traffic between VPN and internal networks

== Related Documentation ==

* [Network Architecture](network-architecture.md) - Network topology

* [Security Architecture](security.md) - Security features

* [OpenVPN Server](index.md) - VPN configuration

[[Category:Documentation]]
[[Category:Documentation/System]]

System:Security

2026-01-01T13:44:30Z

Josh: Content added - configuration guide: Security Architecture (11 sections)

This document describes the security architecture of the reverse proxy system.

== Defense in Depth ==

The system uses multiple layers of security:

=== '''Public Layer''': Nginx with SSL/TLS encryption ===
== '''VPN Layer''': Encrypted tunnel between VPS and NAS ==
== '''Internal Layer''': Services only accessible via VPN ==
== '''Certificate Security''': Automatic renewal prevents expired certificates ==

== Security Benefits ==

* '''No Direct Exposure''': Synology NAS is not directly accessible from the internet

* '''Encrypted Traffic''': All public traffic uses HTTPS

* '''Isolated Network''': Internal services communicate over VPN

* '''Certificate Management''': Automatic SSL certificate renewal

== Security Components ==

=== SSL/TLS Encryption ===

* All public-facing traffic uses HTTPS

* Let's Encrypt certificates automatically renew

* HTTP traffic is redirected to HTTPS

=== VPN Encryption ===

* OpenVPN provides encrypted tunnel between VPS and NAS

* All internal traffic is encrypted through VPN

* Certificate-based authentication for VPN clients

=== Network Isolation ===

* Internal services only accessible via VPN

* No direct internet exposure of Synology NAS

* Firewall rules control traffic flow

== Related Documentation ==

* [Network Architecture](network-architecture.md) - Network topology

* [Key Components](components.md) - Component details

* [OpenVPN Server](index.md) - VPN security configuration

[[Category:Documentation]]
[[Category:Documentation/System]]

System:Service Management

2026-01-01T13:44:29Z

Josh: Content added - troubleshooting guide: Service Management (19 sections)

This document describes how to manage services in the reverse proxy system.

== Nginx Service ==

=== Status Check ===

<pre class="lang-bash">
systemctl status nginx
</pre>

=== Configuration Test ===

<pre class="lang-bash">
nginx -t
</pre>

=== Reload Configuration ===

Reload nginx to apply new configuration (graceful, no downtime):

<pre class="lang-bash">
systemctl reload nginx
</pre>

=== Restart Service ===

<pre class="lang-bash">
systemctl restart nginx
</pre>

== Logs ==

=== Access Logs ===

'''Location''': <code>/var/log/nginx/access.log</code>

* Records all HTTP requests

* Useful for traffic analysis and debugging

=== Error Logs ===

'''Location''': <code>/var/log/nginx/error.log</code>

* Records errors and warnings

* First place to check for issues

=== View Logs ===

<pre class="lang-bash">
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
</pre>

== Maintenance ==

=== Regular Tasks ===

==== '''Certificate Monitoring''': Verify auto-renewal is working (certbot handles this) ====
== '''Log Review''': Check nginx logs for errors or unusual activity ==
== '''Package Updates''': Keep nginx and certbot updated ==
== '''Configuration Backups''': Backup nginx configurations periodically ==

=== Backup Commands ===

<pre class="lang-bash">
==== Backup nginx configurations ====
tar -czf nginx-config-backup-$(date +%Y%m%d).tar.gz /etc/nginx/sites-available/

== Backup SSL certificates (optional, usually not needed) ==
tar -czf certbot-backup-$(date +%Y%m%d).tar.gz /etc/letsencrypt/
</pre>

== Related Documentation ==

* [Network Architecture](network-architecture.md) - Network overview

* [[Documentation:Index|Troubleshooting]] - Service troubleshooting

[[Category:Documentation]]
[[Category:Documentation/System]]

Main Page

2026-01-01T13:28:54Z

Josh: Updated Main Page with comprehensive documentation links

== Welcome to the jb-vpn.uk Wiki ==

This wiki contains comprehensive documentation for the reverse proxy system that forwards traffic from public subdomains to services on a Synology NAS via OpenVPN.

== Documentation ==

The following documentation is available:

=== Cursor SSH ===

* [[Cursor SSH:Quick Reference|Quick Reference]]
* [[Cursor SSH:Setup|Setup]]

=== OpenVPN ===

* [[OpenVPN:Certificate Management|Certificate Management]]
* [[OpenVPN:Client Configuration|Client Configuration]]
* [[OpenVPN:Integration|Integration]]
* [[OpenVPN:Raspberry Pi Auto Connect|Raspberry Pi Auto Connect]]
* [[OpenVPN:Server Configuration|Server Configuration]]
* [[OpenVPN:User Management|User Management]]

=== SSH Port Forwarding ===

* [[SSH Port Forwarding:Best Practices|Best Practices]]
* [[SSH Port Forwarding:Configuration|Configuration]]
* [[SSH Port Forwarding:Management|Management]]
* [[SSH Port Forwarding:Overview|Overview]]
* [[SSH Port Forwarding:Quickstart|Quickstart]]

=== Services ===

* [[Services:Current Services|Current Services]]

==== Adding Services ====
* [[Services:Best Practices|Best Practices]]
* [[Services:Configuration Options|Configuration Options]]
* [[Services:Prerequisites|Prerequisites]]
* [[Services:Service Examples|Service Examples]]
* [[Services:Step By Step|Step By Step]]

=== System ===

* [[System:Components|Components]]
* [[System:DNS Requirements|DNS Requirements]]
* [[System:Network Architecture|Network Architecture]]
* [[System:Security|Security]]
* [[System:Service Management|Service Management]]

=== Troubleshooting ===

* [[Troubleshooting:Nginx Troubleshooting|Nginx Troubleshooting]]
* [[Troubleshooting:Openvpn Troubleshooting|Openvpn Troubleshooting]]
* [[Troubleshooting:Port Forwarding Troubleshooting|Port Forwarding Troubleshooting]]
* [[Troubleshooting:Service Troubleshooting|Service Troubleshooting]]

=== Wiki Management ===

* [[Wiki Management:Upload Instructions|Upload Instructions]]

== Quick Links ==

=== Services ===
* [[Main Page|Wiki Home]] - This page
* [https://dsm.jb-vpn.uk Synology DSM] - Synology management interface
* [https://plex.jb-vpn.uk Plex Media Server] - Media server
* [https://vps.jb-vpn.uk VPS Default] - VPS web directory

== System Information ==

* '''VPS IP''': 87.106.61.62
* '''VPN Network''': 10.8.0.0/24
* '''Synology NAS''': 10.8.0.2 (via VPN)
* '''Web Server''': Nginx
* '''SSL''': Let's Encrypt (Certbot)

== Quick Reference Commands ==

<pre class="lang-bash">
# Test nginx configuration
nginx -t

# Reload nginx
systemctl reload nginx

# Check SSL certificates
certbot certificates

# View nginx logs
tail -f /var/log/nginx/error.log

# Test service
curl -I https://wiki.jb-vpn.uk
</pre>

Wiki Management:Upload Instructions

2026-01-01T13:28:41Z

Josh: Minor update - troubleshooting guide: Uploading Documentation to Wiki (24 sections) (wiki management)

= Uploading Documentation to Wiki =

This guide explains how to upload the documentation files to your MediaWiki instance.

== Option 1: Automated Upload (Recommended) ==

Use the unified wiki manager script to automatically upload all documentation files.

=== Prerequisites ===

The script requires <code>mwclient</code> library, which should already be installed:
<pre class="lang-bash">
pip3 install --break-system-packages mwclient
</pre>

=== Usage ===

'''First time setup''' - Store credentials:
<pre class="lang-bash">
python3 /root/wiki_manager.py --store-credentials
</pre>

'''Upload all documentation files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload
</pre>

'''Update the Main Page with documentation links:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

'''Do both at once:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --update-main-page
</pre>

'''Check sync status:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --status
</pre>

'''Sync changes from wiki to local files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --sync
</pre>

'''Delete orphaned wiki pages''' (pages that no longer have corresponding local files):
<pre class="lang-bash">
= Preview what would be deleted (dry run - recommended first) =
python3 /root/wiki_manager.py --delete-orphaned --dry-run

= Actually delete orphaned pages (with confirmation) =
python3 /root/wiki_manager.py --delete-orphaned

= Delete orphaned pages without confirmation (non-interactive) =
python3 /root/wiki_manager.py --delete-orphaned -y
</pre>

'''Upload new docs and delete old orphaned pages in one go:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --delete-orphaned -y
</pre>

=== Managing Orphaned Pages ===

When you restructure documentation (e.g., breaking large files into smaller sub-pages), old wiki pages may become "orphaned" - they exist on the wiki but no longer have corresponding local files.

The <code>--delete-orphaned</code> feature helps you clean up these old pages:

= '''Finds orphaned pages''': Automatically searches for all <code>Documentation:</code> pages on the wiki and compares them with your local files =
= '''Shows what would be deleted''': Lists all orphaned pages with their content length =
= '''Safety features''': =
* Use <code>--dry-run</code> first to preview what would be deleted

* Requires confirmation (or use <code>-y</code> flag for non-interactive mode)

* Shows detailed information about each page before deletion

'''Example workflow after restructuring documentation:'''

<pre class="lang-bash">
= 1. First, preview what would be deleted =
python3 /root/wiki_manager.py --delete-orphaned --dry-run

= 2. If the list looks correct, actually delete them =
python3 /root/wiki_manager.py --delete-orphaned -y

= 3. Upload the new restructured documentation =
python3 /root/wiki_manager.py --upload --update-main-page
</pre>

'''Note''': The script only deletes pages in the <code>Documentation:</code> namespace that don't have corresponding local files. It will never delete pages that still have local files, ensuring your active documentation is always preserved.

=== Customizing Upload Comments ===

By default, the script uses the comment "Uploaded documentation from markdown files" for all uploads. You can customize this behavior in two ways:

==== Option 1: Custom Comment ====

Use the <code>--comment</code> flag to specify a custom comment that will be used for all uploads:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --comment "Updated documentation for v2.0"
</pre>

This is useful when you want to provide a specific message for a batch of uploads, such as:
* Version updates: <code>--comment "Documentation update for version 2.1"</code>

* Feature additions: <code>--comment "Added new SSH port forwarding documentation"</code>

* Bug fixes: <code>--comment "Fixed formatting issues in configuration guides"</code>

==== Option 2: Auto-Generated Comments ====

Use the <code>--auto-comment</code> flag to automatically generate meaningful comments based on the content of each file:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --auto-comment
</pre>

The auto-comment feature analyzes each file to generate contextual comments such as:
* <code>"Added configuration guide: SSH Port Forwarding (configuration)"</code>

* <code>"Major update - troubleshooting guide: Port Forwarding Troubleshooting (3 sections) (troubleshooting)"</code>

* <code>"Content added - overview: System Overview (getting started)"</code>

The auto-comment generator:
* Detects document type (troubleshooting guide, configuration guide, overview, etc.)

* Identifies whether it's a new page or an update

* Compares with existing wiki content to detect changes (major update, content added, minor update)

* Extracts the document title from markdown headers

* Counts sections to provide context

* Categorizes based on file path

'''Note''': The <code>--comment</code> flag takes precedence over <code>--auto-comment</code>. If both are specified, the custom comment will be used.

'''Examples:'''

<pre class="lang-bash">
= Upload with auto-generated comments =
python3 /root/wiki_manager.py --upload --auto-comment

= Upload with custom comment and update main page =
python3 /root/wiki_manager.py --upload --update-main-page --comment "Major documentation update"

= Upload with custom comment in non-interactive mode =
python3 /root/wiki_manager.py --upload --comment "Quick fix" -y
</pre>

=== What the Script Does ===

The unified wiki manager script:
= Automatically discovers all documentation files in the <code>/root/documentation/</code> directory =
= Converts markdown files to MediaWiki wikitext format =
= Maps files to wiki pages based on folder structure: =
* <code>getting-started/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>getting-started/system-overview/index.md</code> → <code>Documentation:Index</code>)

* <code>configuration/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>configuration/adding-services/step-by-step.md</code> → <code>Documentation:Step By Step</code>)

* <code>troubleshooting/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>troubleshooting/port-forwarding-troubleshooting.md</code> → <code>Documentation:Port Forwarding Troubleshooting</code>)

* <code>wiki-management/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>wiki-management/upload-instructions.md</code> → <code>Documentation:Upload Instructions</code>)

= Uploads all documentation pages to the wiki =
= Can update the Main Page with links to all documentation =
= Can identify and delete orphaned wiki pages (pages without corresponding local files) =

=== Customizing Wiki URL ===

The script automatically detects the wiki URL. To specify a custom URL, edit the script or use environment variables.

----

== Option 2: Manual Upload ==

If you prefer to upload manually or the script doesn't work:

=== Step 1: Access the Wiki ===

= Navigate to your wiki: [https://wiki.jb-vpn.uk/index.php?title=Main_Page https://wiki.jb-vpn.uk/index.php?title=Main_Page] =
= Log in with your MediaWiki account =

=== Step 2: Create the Documentation Namespace ===

= Go to: [https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage] =
= Create a page named <code>Documentation:Index</code> =
= Or navigate directly: [https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit] =

=== Step 3: Convert and Paste Content ===

For each documentation file:

= '''Read the markdown file''': =
<pre class="lang-bash">
cat /root/documentation/index.md
</pre>

= '''Manually convert key elements''': =
* <code># Header</code> → <code>= Header =</code>

* <code>## Header</code> → <code>== Header ==</code>

* <code>### Header</code> → <code>=== Header ===</code>

* Inline code: `<code> </code>code<code> </code><code> → </code><code>code</code><code>

* </code>'''bold'''<code> → </code>'''bold'''<code>

* </code>*italic*<code> → </code>*italic*<code>

* Code blocks: Wrap with </code><syntaxhighlight lang="bash"><code> and </code></syntaxhighlight><code>

= '''Create the pages''': =
* </code>Documentation:Index<code> (from </code>documentation/index.md<code>)

* </code>Documentation:System_Overview<code> (from </code>documentation/getting-started/system-overview.md<code>)

* </code>Documentation:Adding_Services<code> (from </code>documentation/configuration/adding-services.md<code>)

* </code>Documentation:Current_Services<code> (from </code>documentation/configuration/current-services.md<code>)

=== Step 4: Add Navigation ===

Create a navigation template or update the main page to link to:
* </code>[Documentation Index](index.md)<code>

* </code>[System Overview](System_Overview.md)<code>

* </code>[Adding Services](Adding_Services.md)<code>

* </code>[Current Services](Current_Services.md)<code>

----

== Option 3: Using MediaWiki API with curl ==

You can also use curl to upload via the MediaWiki API:

=== Step 1: Get Login Token ===

<pre class="lang-bash">
WIKI_URL="http://10.8.0.2:8080"
USERNAME="your_username"
PASSWORD="your_password"

= Get login token =
LOGIN_TOKEN=$(curl -s "$WIKI_URL/api.php?action=query&meta=tokens&type=login&format=json" | grep -oP '(?<="logintoken":")[^"]''' # Login
LOGIN_RESULT=$(curl -s -c cookies.txt -b cookies.txt \
-d "action=login" \
-d "lgname=$USERNAME" \
-d "lgpassword=$PASSWORD" \
-d "lgtoken=$LOGIN_TOKEN" \
-d "format=json" \
"$WIKI_URL/api.php")

echo "Login: $LOGIN_RESULT"
</pre>

=== Step 2: Get Edit Token ===

<pre class="lang-bash">
EDIT_TOKEN=$(curl -s -b cookies.txt \
"$WIKI_URL/api.php?action=query&meta=tokens&format=json" | \
grep -oP '(?<="csrftoken":")[^"])''')
</pre>

=== Step 3: Upload Page ===

<pre class="lang-bash">
PAGE_NAME="Documentation:Index"
CONTENT=$(cat /root/documentation/index.md | sed 's/#/=/g') # Basic conversion

curl -s -b cookies.txt \
-d "action=edit" \
-d "title=$PAGE_NAME" \
-d "text=$CONTENT" \
-d "token=$EDIT_TOKEN" \
-d "format=json" \
"$WIKI_URL/api.php"
</pre>

'''Note''': This method requires manual markdown-to-wikitext conversion and is more complex.

----

== Troubleshooting ==

=== Script Authentication Issues ===

If login fails:
= Verify your MediaWiki username and password =
= Check that your account has edit permissions =
= Ensure the wiki is accessible from the VPS =

=== Connection Issues ===

If you can't connect:
<pre class="lang-bash">
= Test connectivity =
curl -I http://10.8.0.2:8080
curl -I https://wiki.jb-vpn.uk

= Test API =
curl "http://10.8.0.2:8080/api.php?action=query&meta=siteinfo&format=json"
</pre>

=== Permission Issues ===

Ensure your MediaWiki account has:
* </code>edit<code> permission

* </code>createpage` permission (if pages don't exist)

----

=== Updating the Main Page ===

To update the Main Page with links to all documentation:

<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

This will add a comprehensive list of all documentation pages to the Main Page.

=== Complete Workflow Example ===

Here's a complete example workflow for restructuring documentation:

<pre class="lang-bash">
= 1. Preview orphaned pages that would be deleted =
python3 /root/wiki_manager.py --delete-orphaned --dry-run

= 2. Delete orphaned pages (if the preview looks correct) =
python3 /root/wiki_manager.py --delete-orphaned -y

= 3. Upload all new/updated documentation =
python3 /root/wiki_manager.py --upload --auto-comment

= 4. Update the Main Page with new documentation structure =
python3 /root/wiki_manager.py --update-main-page

= Or do steps 3 and 4 together: =
python3 /root/wiki_manager.py --upload --update-main-page --auto-comment
</pre>

----

[[Category:Documentation]]
[[Category:Documentation/Wiki Management]]