diff --git a/docs/docs/about/backers.md b/docs/docs/about/backers.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/docs/about/conventions.md b/docs/docs/about/conventions.md index aafb43b89..c518fb25a 100644 --- a/docs/docs/about/conventions.md +++ b/docs/docs/about/conventions.md @@ -33,6 +33,15 @@ This defines what the default value for a setting is. : Specified setting has a default value : Specified setting has no default value and is empty +: Specified setting is automatically computed by the app + +
+ +## Command { #command data-toc-label="Command" } + +This defines a command + +: Specified setting has a default value
@@ -50,15 +59,42 @@ Items listed with this symbol indicate that they are required to be set. ## Customization { #customization data-toc-label="Customization" } -This symbol denotes that the item described is a customization which affects the overall look of the plugin. +This symbol denotes that the item described is a customization which affects the overall look of the app.
-## Utility { data-toc-label="Utility" } +## 3rd Party { data-toc-label="3rd Party" } This symbol denotes that the item described is classified as something that changes the overall functionality of the plugin. - [Insiders]: insiders/index.md +
+ +### – Metadata property { #metadata data-toc-label="Metadata property" } + +This symbol denotes that the item described is a metadata property, which can +be used in Markdown documents as part of the front matter definition. + +
+ +### – Multiple instances { #multiple-instances data-toc-label="Multiple instances" } + +This symbol denotes that the plugin supports multiple instances, i.e, that it +can be used multiple times in the `plugins` setting in `mkdocs.yml`. + +
+ +### – Optional feature { #feature data-toc-label="Optional feature" } + +Most of the features are hidden behind feature flags, which means they must +be explicitly enabled via `mkdocs.yml`. This allows for the existence of +potentially orthogonal features. + +
+ +### – Backers only { data-toc-label="Backers only" } + +The pumping heart symbol denotes that a specific feature or behavior is only +available to backers. Normal users will not have access to this particular item.
diff --git a/docs/docs/about_csf.md b/docs/docs/about_csf.md index aa8e5d58a..9c5191aa8 100644 --- a/docs/docs/about_csf.md +++ b/docs/docs/about_csf.md @@ -12,16 +12,14 @@ ConfigServer Firewall also comes with a service called **Login Failure Daemon**,
-```embed -url: https://configserver.com/configserver-security-and-firewall/ -name: ConfigServer Firewall Official Website -desc: A firewall configuration script created to provide better security for your server -image: https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSjXOa4WN-mW3gXnIo_hEY6uAwoi2v_e02eG3TCHxSwIY70Y_OzErdaeaepXFoRa2sYx8M&usqp=CAU -favicon: https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSjXOa4WN-mW3gXnIo_hEY6uAwoi2v_e02eG3TCHxSwIY70Y_OzErdaeaepXFoRa2sYx8M&usqp=CAU -favicon_size: 25 -target: new -accent: 4C59BFE0 -``` +When installing CSF; you will be provided with two services: + +| Service | Description | +| --- | --- | +| `csf` | **ConfigServer Firewall** (csf): SPI iptables firewall which allows you to restrict what is allowed to communicate with your server. | +| `lfd` | **Login Failure Daemon** (lfd): Process that runs all the time and periodically (every X seconds) scans the latest log file entries for login attempts against your server that continually fail within a short period of time. | + +

diff --git a/docs/docs/cheatsheet/commands.md b/docs/docs/cheatsheet/commands.md new file mode 100644 index 000000000..212ada3d6 --- /dev/null +++ b/docs/docs/cheatsheet/commands.md @@ -0,0 +1,719 @@ +--- +title: "Cheatsheet: Commands" +tags: + - cheatsheet + - configure +--- + +# Cheatsheet: Commands +When installing, configuring, and running CSF; it is helpful to know where files and folders are stored within your system, and what their purpose is. A list of these files and folders used by CSF are provided below: + +
+ +### Enable + + +Enable csf and lfd if previously disabled + +```shell +sudo csf -e +``` + +
+ +### Disable + + +Disable csf and lfd completely + +```shell +sudo csf -x +``` + +
+ +### Start + + +Starts the firewall and applies any rules that have been configured at startup. + +```shell +sudo csf -s +``` + +
+ +### Stop + + +Flush/Stop firewall rules (Note: lfd may restart csf) + +```shell +sudo csf -f +``` + +=== "stop" + + ``` + Flushing chain `INPUT' + Flushing chain `FORWARD' + Flushing chain `CC_ALLOWPORTS' + [ ... ] + Deleting chain `ALLOWIN' + Deleting chain `ALLOWOUT' + Deleting chain `CC_ALLOWP' + Deleting chain `CC_ALLOWPORTS' + [ ... ] + ``` + +
+ +### Restart + + +Restart firewall rules (csf) + +```shell +sudo csf -r +``` + +=== "restart" + + ``` + Flushing chain `INPUT' + Flushing chain `FORWARD' + Flushing chain `OUTPUT' + Flushing chain `ALLOWIN' + Flushing chain `ALLOWOUT' + Flushing chain `CC_ALLOWP' + Flushing chain `CC_ALLOWPORTS' + [ ... ] + ``` + +
+ +### Quick Restart + + +Quick restart (csf restarted by lfd) + +```shell +sudo csf -q +``` + +=== "startq" + + ``` + lfd will restart csf within the next 5 seconds + ``` + +
+ +### Force Restart + + +Force CLI restart regardless of LFDSTART setting + +```shell +sudo csf -sf +``` + +=== "startf" + + ``` + Flushing chain `INPUT' + Flushing chain `FORWARD' + Flushing chain `OUTPUT' + Flushing chain `ALLOWIN' + Flushing chain `ALLOWOUT' + Flushing chain `CC_ALLOWP' + Flushing chain `CC_ALLOWPORTS' + [ ... ] + ``` + +
+ +### Restart All + + +Restart firewall rules (csf) and then restart lfd daemon. Both csf and then lfd should be restarted after making any changes to the configuration files + +```shell +sudo csf -ra +``` + +=== "restartall" + + ``` + Flushing chain `INPUT' + Flushing chain `FORWARD' + Flushing chain `OUTPUT' + Flushing chain `ALLOWIN' + Flushing chain `ALLOWOUT' + Flushing chain `CC_ALLOWP' + Flushing chain `CC_ALLOWPORTS' + [ ... ] + ``` + +
+ +### Cluster Restart + + +Cluster restart csf and lfd + +```shell +sudo csf -crs +``` + +
+ +### Manage Lfd Daemon + + +Actions to take with the lfd daemon + +```shell +sudo csf --lfd stop +sudo csf --lfd start +sudo csf --lfd restart +sudo csf --lfd status +``` + +=== "stop" + + ``` + No output + ``` + +=== "start" + + ``` + No output + ``` + +=== "restart" + + ``` + ● lfd.service - ConfigServer Firewall & Security - lfd + Loaded: loaded (/lib/systemd/system/lfd.service; enabled; preset: enabled) + Active: active (running) since 15ms ago + Process: 3769 ExecStart=/usr/sbin/lfd (code=exited, status=0/SUCCESS) + Main PID: 3782 (lfd - starting) + Tasks: 1 (limit: 4613) + Memory: 38.7M + CPU: 366ms + CGroup: /system.slice/lfd.service + ├─3782 "lfd - starting" + └─3784 "lfd - starting" + + systemd[1]: Starting lfd.service - ConfigServer Firewall & Security - lfd... + systemd[1]: Started lfd.service - ConfigServer Firewall & Security - lfd. + ``` + +=== "status" + + ``` + ● lfd.service - ConfigServer Firewall & Security - lfd + Loaded: loaded (/lib/systemd/system/lfd.service; enabled; preset: enabled) + Active: active (running) since 1min 3s ago + Process: 3769 ExecStart=/usr/sbin/lfd (code=exited, status=0/SUCCESS) + Main PID: 3782 (lfd - sleeping) + Tasks: 2 (limit: 4613) + Memory: 45.2M + CPU: 9.476s + CGroup: /system.slice/lfd.service + ├─3782 "lfd - sleeping" + └─3791 "lfd UI" + + systemd[1]: Starting lfd.service - ConfigServer Firewall & Security - lfd... + systemd[1]: Started lfd.service - ConfigServer Firewall & Security - lfd. + ``` + +
+ +### Check for Updates + + +Check for updates to csf but do not upgrade + +```shell +sudo csf -c +``` + +=== "Output" + + ``` + csf is already at the latest version: v14.20 + ``` + +
+ +### Update + + +Check for updates to csf and upgrade if available + +```shell +sudo csf -u +``` + +
+ +### Update (Force) + + +Force an update of csf whether and upgrade is required or not + +```shell +sudo csf -uf +``` + +
+ +### Version + + +Show csf version + +```shell +sudo csf -v +``` + +=== "Output" + + ``` + csf: v14.20 (generic) + ``` + +
+ +### List Firewall Rules (IPv4) + + +List/Show the IPv4 iptables configuration + +```shell +sudo csf -l +``` + +=== "Output" + + ``` + iptables filter table + ===================== + Chain INPUT (policy DROP 0 packets, 0 bytes) + num pkts bytes target prot opt in out source destination + 1 33 2492 ACCEPT udp -- * * 0.0.0.0/0 0.0.0.0/0 multiport dports 4000,5353 + 2 758 55610 ACCEPT tcp -- * * 0.0.0.0/0 0.0.0.0/0 multiport dports 4000 + 3 0 0 ACCEPT udp -- * * 0.0.0.0/0 0.0.0.0/0 multiport dports 5353 + 4 5209K 28G LOCALINPUT all -- !lo * 0.0.0.0/0 0.0.0.0/0 + 13 3 180 ACCEPT tcp -- !lo * 0.0.0.0/0 0.0.0.0/0 ctstate NEW tcp dpt:22 + 14 998 56956 ACCEPT tcp -- !lo * 0.0.0.0/0 0.0.0.0/0 ctstate NEW tcp dpt:25 + 15 123 5612 ACCEPT tcp -- !lo * 0.0.0.0/0 0.0.0.0/0 ctstate NEW tcp dpt:53 + 16 16 680 ACCEPT tcp -- !lo * 0.0.0.0/0 0.0.0.0/0 ctstate NEW tcp dpt:853 + 17 2 100 ACCEPT tcp -- !lo * 0.0.0.0/0 0.0.0.0/0 ctstate NEW tcp dpt:80 + 18 74 3148 ACCEPT tcp -- !lo * 0.0.0.0/0 0.0.0.0/0 ctstate NEW tcp dpt:110 + 19 125 5624 ACCEPT tcp -- !lo * 0.0.0.0/0 0.0.0.0/0 ctstate NEW tcp dpt:143 + ``` + +
+ +
+ +### List Firewall Rules (IPv6) + + +List/Show the IPv6 ip6tables configuration + +```shell +sudo csf -l6 +``` + +=== "Output" + + ``` + ip6tables filter table + ====================== + Chain INPUT (policy DROP 0 packets, 0 bytes) + num pkts bytes target prot opt in out source destination + 8 0 0 ACCEPT all !lo * ::/0 ::/0 ctstate RELATED,ESTABLISHED + 9 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:20 + 10 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:21 + 11 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:22 + 12 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:25 + 13 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:53 + 14 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:853 + 15 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:80 + 16 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:110 + 17 0 0 ACCEPT tcp !lo * ::/0 ::/0 ctstate NEW tcp dpt:143 + ``` + +
+ +### Add IP to Allow List + + +Allow an IP and add to `/etc/csf/csf.allow` + +```shell +sudo csf -a +sudo csf -a 142.250.189.142 +``` + +=== "Output" + + ``` + Adding 142.250.189.142 to csf.allow and iptables ACCEPT... + csf: IPSET adding [142.250.189.142] to set [chain_ALLOW] + ``` + +
+ +### Remove IP to Allow List + + +Remove an IP from `/etc/csf/csf.allow` and delete rule + +```shell +sudo csf -ar +``` + +
+ +### Add IP to Deny List + + +Deny an IP and add to `/etc/csf/csf.deny` + +```shell +sudo csf -d +``` + +
+ +### Remove IP from Deny List + + +Unblock an IP and remove from `/etc/csf/csf.deny` + +```shell +sudo csf -dr +``` + +
+ +### Remove All IPs from Deny List + + +Remove and unblock all entries in `/etc/csf/csf.deny` + +```shell +sudo csf -df +``` + +=== "Output" + + ``` + csf: all entries removed from csf.deny + ``` + +
+ +### Grep Search for IP + + +Search the iptables and ip6tables rules for a match (e.g. IP, CIDR, Port Number) + +```shell +sudo csf -g +sudo csf -g 22 +sudo csf -g ACCEPT +``` + +
+ +### Lookup IP + + +Lookup IP address geographical information using CC_LOOKUPS setting in `/etc/csf/csf.conf` + +```shell +sudo csf -i +sudo csf -i 142.250.189.142 +``` + +=== "Output" + + ``` + 142.250.189.142 (US/United States/mia09s26-in-f14.1e100.net) + ``` + +
+ +### View Temp Allow/Ban List + + +Displays the current list of temporary allow and deny IP entries with their TTL and comment + +```shell +sudo csf -t +``` + +=== "Output" + + ``` + A/D IP address Port Dir Time To Live Comment + ALLOW 142.250.189.142 * inout 58m 56s Manually added: 142.250.189.142 (US/United States/mia09s26-in-f14.1e100.net) + ``` + +
+ +### Remove Temp Allow/Ban IP + + +Remove an IP from the temporary IP ban or allow list + +```shell +sudo csf -tr +sudo csf -tr 142.250.189.142 +``` + +=== "Output" + + ``` + ACCEPT all opt -- in !lo out * 142.250.189.142 -> 0.0.0.0/0 + ACCEPT all opt -- in * out !lo 0.0.0.0/0 -> 142.250.189.142 + csf: 142.250.189.142 temporary allow removed + ``` + +
+ +### Remove Temp Ban IP + + +Remove an IP from the temporary IP ban list only + +```shell +sudo csf -trd +``` + +
+ +### Remove Temp Allow IP + + +Remove an IP from the temporary IP allow list only + +```shell +sudo csf -tra +``` + +
+ +### Add Temp Block IP + + +Add an IP to the temp IP ban list. ttl is how long to blocks for (default:seconds, can use one suffix of h/m/d). Optional port. +Optional direction of block can be one of: in, out or inout (default:in) + +```shell +sudo csf -td +``` + +
+ +### Add Temp Allow IP + + +Add an IP to the temp IP allow list (default:inout) + +```shell +sudo csf -ta +sudo csf -ta 142.250.189.142 +``` + +=== "Output" + + ``` + ACCEPT all opt -- in !lo out * 142.250.189.142 -> 0.0.0.0/0 + ACCEPT all opt -- in * out !lo 0.0.0.0/0 -> 142.250.189.142 + ``` + +
+ +### Flush All Temp IP Entries + + +Flush all IPs from the temporary IP entries + +```shell +sudo csf -tf +``` + +=== "Output" + + ``` + csf: There are no temporary IP bans + ACCEPT all opt -- in !lo out * 142.250.189.142 -> 0.0.0.0/0 + ACCEPT all opt -- in * out !lo 0.0.0.0/0 -> 142.250.189.142 + csf: 142.250.189.142 temporary allow removed + ``` + +
+ +### Initiate Lfd Log Scanner + + +Initiate Log Scanner report via lfd + +```shell +sudo csf -lr +``` + +
+ +If you receive the following error in console: + +=== "Output" + + ``` + Option LOGSCANNER needs to be enabled in csf.conf for this feature + ``` + +
+ +Open your `csf.conf` configuration file, locate the setting `LOGSCANNER`, and change the value to `1`: + +```ini hl_lines="18" +############################################################################### +# SECTION:Log Scanner +############################################################################### +# Log Scanner. This feature will send out an email summary of the log lines of +# each log listed in /etc/csf/csf.logfiles. All lines will be reported unless +# they match a regular expression in /etc/csf/csf.logignore +# +# File globbing is supported for logs listed in /etc/csf/csf.logfiles. However, +# be aware that the more files lfd has to track, the greater the performance +# hit. Note: File globs are only evaluated when lfd is started +# +# Note: lfd builds the report continuously from lines logged after lfd has +# started, so any lines logged when lfd is not running will not be reported +# (e.g. during reboot). If lfd is restarted, then the report will include any +# lines logged during the previous lfd logging period that weren't reported +# +# 1 to enable, 0 to disable +LOGSCANNER = "0" +``` + +
+ +Then go back to console and re-run the command. + +
+ +### View Ports + + +View ports on the server that have a running process behind them listening for external connections + +```shell +sudo csf -p +``` + +=== "Output" + + ``` + Ports listening for external connections and the executables running behind them: + Port/Proto Open Conn PID/User Command Line Executable + 631/tcp -/- - (1090/root) /usr/sbin/cupsd -l /usr/sbin/cupsd + 8546/tcp 4/6 - (4627/root) lfd UI /usr/bin/perl + 5353/udp -/- - (337/systemd-resolve /lib/systemd/systemd-resolved /usr/lib/systemd/systemd-resolved + 5353/udp -/- - (702/avahi) avahi-daemon: running [local] /usr/sbin/avahi-daemon + 40857/udp -/- - (702/avahi) avahi-daemon: running [local] /usr/sbin/avahi-daemon + 49833/udp -/- - (702/avahi) avahi-daemon: running [local] /usr/sbin/avahi-daemon + ``` + +
+ +### View Graphs + + +Generate System Statistics html pages and images for a given graph type into a given directory. See ST_SYSTEM for requirements + +`[graph type]` + +: - disk + - apachework + - mysqlslowqueries + - cpu + - load + - mysqlconns + - net + - diskw + - apachecpu + - email + - temp + - apacheconn + - mysqlqueries + - mem + - mysqldata + +```shell +sudo csf --graphs +sudo csf --graphs mem /home/$USER/graphs +``` + +
+ +If you run the above command and see the error: + +=== "Output" + + ``` + ST_SYSTEM is disabled + ``` + +
+ +Open your `csf.conf` configuration file, locate the setting `ST_SYSTEM`, and change the value to `1`: + +```ini hl_lines="14" +# This option will gather basic system statstics. Through the UI it displays +# various graphs for disk, cpu, memory, network, etc usage over 4 intervals: +# . Hourly (per minute) +# . 24 hours (per minute) +# . 7 days (per minute averaged over an hour) +# . 30 days (per minute averaged over an hour) - user definable +# The data is stored in /var/lib/csf/stats/system and the option requires the +# perl GD::Graph module +# +# Note: Disk graphs do not show on Virtuozzo/OpenVZ servers as the kernel on +# those systems do not store the required information in /proc/diskstats +# On new installations or when enabling this option it will take time for these +# graphs to be populated +ST_SYSTEM = "0" +``` + +
+ +If you receive the error: + +=== "Output" + + ``` + Perl module GD::Graph is not installed/working + ``` + +
+ +Install the package `libgd-graph-perl`: +```shell +sudo apt-get install libgd-graph-perl +``` + +
+ +--- + +
diff --git a/docs/docs/configure/conf.md b/docs/docs/cheatsheet/conf.md similarity index 99% rename from docs/docs/configure/conf.md rename to docs/docs/cheatsheet/conf.md index 0db5b2a49..c467f008d 100644 --- a/docs/docs/configure/conf.md +++ b/docs/docs/cheatsheet/conf.md @@ -4,7 +4,6 @@ tags: - configure --- -markdown # Configure: csf.conf Two versions of the config file have been provided below. A **full version** which contains comments, and a **clean version** which contains no comments and only the config settings. diff --git a/docs/docs/cheatsheet/structure.md b/docs/docs/cheatsheet/structure.md new file mode 100644 index 000000000..4e26000b9 --- /dev/null +++ b/docs/docs/cheatsheet/structure.md @@ -0,0 +1,63 @@ +--- +title: "Cheatsheet: File & Folder Structure" +tags: + - cheatsheet + - configure +--- + +# Cheatsheet: File & Folder Structure +When installing, configuring, and running CSF; it is helpful to know where files and folders are stored within your system, and what their purpose is. A list of these files and folders used by CSF are provided below: + +
+ +## Directory Structure +Directories associated with ConfigServer Filewall which house all of the files used to configure and manage CSF. + +| Folder | Description | +| ------------------------- | ------------------------------- | +| `/etc/csf/` | configuration files | +| `/var/lib/csf/` | temporary data files | +| `/usr/local/csf/bin/` | scripts | +| `/usr/local/csf/lib/` | perl modules and static data | +| `/usr/local/csf/tpl/` | email alert templates | + +
+ +--- + +
+ +## File Structure +Files associated with ConfigServer Firewall configuration and management. + +| File | Description | +| ------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `/etc/csf/csf.conf` | The main configuration file. | +| `/etc/csf/csf.allow` | A list of IP's and CIDR addresses that should always be allowed through the firewall. | +| `/etc/csf/csf.deny` | A list of IP's and CIDR addresses that should never be allowed through the firewall. | +| `/etc/csf/csf.ignore` | A list of IP's and CIDR addresses that the login failure daemon should ignore and not not block if detected. | +| `/etc/csf/csf.*ignore` | Various ignore files that list files, users, IP's that the login failure daemon should ignore. | +| `/lib/systemd/system/lfd.service` | Service file for lfd (ConfigServer Firewall) | +| `/lib/systemd/system/csf.service` | Service file for csf (Login Failure Daemon) | + +
+ +--- + +
+ +## Patcher Files +The following files are associated with the ConfigServer Firewall patcher which adds special iptable rules so that CSF can communicate with Docker & OpenVPN. + +| File | Description | +| --------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `/usr/local/csf/bin/csfpre.sh` | Patcher **pre** script. Runs before CSF configures iptables | +| `/usr/local/csf/bin/csfpost.sh` | Patcher **post** script. Runs after CSF configures iptables | +| `/usr/local/include/csf/post.d/docker.sh` | Docker patch for CSF which adds firewall rules for Docker and CSF | +| `/usr/local/include/csf/post.d/openvpn.sh` | OpenVPN patch for CSF which adds firewall rules for OpenVPN and CSF | + +
+ +--- + +
diff --git a/docs/docs/cheatsheet/troubleshooting.md b/docs/docs/cheatsheet/troubleshooting.md new file mode 100644 index 000000000..2b19bb87a --- /dev/null +++ b/docs/docs/cheatsheet/troubleshooting.md @@ -0,0 +1,65 @@ +--- +title: "Cheatsheet: Troubleshooting" +tags: + - cheatsheet + - configure +--- + +# Cheatsheet: Troubleshooting +The information below is a list of errors you may receive within CSF, and steps on how to correct each issue. + +
+ +## Can't locate object method "new" via package "Crypt::CBC" at /usr/sbin/csf line *** +This error occurs when **Crypt::CBC** cannot be found. It is sometimes seen when executing commands such as `sudo csf -cp`. + +
+ +To correct the issue, open the file `/usr/sbin/csf` in a text editor. + +Locate the lines: +```conf +use ConfigServer::Sendmail; +use ConfigServer::LookUpIP qw(iplookup); +``` + +Add a new line with `use Crypt::CBC` as shown below: +```hl_lines="3" +use ConfigServer::Sendmail; +use ConfigServer::LookUpIP qw(iplookup); +use Crypt::CBC +``` + +
+ +Save the file, and re-execute your previous command which caused the error. + +
+ +--- + +
+ +## csf[46313]: open3: exec of /sbin/ipset flush failed: No such file or directory at /usr/sbin/csf line ****. +This error occurs when you are missing the package `ipset`. Install it with the following commands: + +
+ +**Debian based systems:** + +```shell +sudo apt update +sudo apt-get install ipset +``` + +**Redhat based systems:** +```shell +sudo yum check-update +sudo yum install ipset +``` + +
+ +--- + +
diff --git a/docs/docs/configure/basics.md b/docs/docs/csf/configure.md similarity index 53% rename from docs/docs/configure/basics.md rename to docs/docs/csf/configure.md index 8ad6ba128..19307169e 100644 --- a/docs/docs/configure/basics.md +++ b/docs/docs/csf/configure.md @@ -1,11 +1,16 @@ --- -title: "Configure: Basics" +title: "Configure & Startup" tags: - configure --- -# Configure: Basics -After you have installed ConfigServer Firewall in the previous chapter; you can start configuring it to suit your server’s requirements. The main configuration file for CSF is located at `/etc/csf/csf.conf`. You can use your preferred text editor to modify the file, such as nano or vim: +# Configure & Startup +After you have installed ConfigServer Firewall in the previous chapter; you can start configuring it to suit your server’s requirements. + +
+ +## Configure +The main configuration file for CSF is located at `/etc/csf/csf.conf`. You can use your preferred text editor to modify the file, such as nano or vim: ```shell sudo nano /etc/csf/csf.conf @@ -30,20 +35,72 @@ The list below outlines just a few of the important settings that you can modify Make sure to review the configuration file and adjust the settings to suit your server’s needs. After making changes to the configuration file, save and exit the text editor. -After you have set your config file to its desired values; you must restart the CSF service to apply the configurations. Open Terminal and run: +Two **csf.conf** configuration files have been provided as examples; a full version, and clean (uncommented) version, and can be viewed on the [csf.conf](./conf.md) page. + +
+ +--- + +
+ +## Start ConfigServer +After you have set your config file to its desired values; you can now start up or restart the CSF service to apply the configurations. Open Terminal and run: + +
+ +### Enable + + +Enable csf and lfd if previously disabled ```shell -sudo csf -r +sudo csf -e ``` -You can also restart both CSF and LFD services with `-ra, --restartall` +
+ +### Start + + +Starts the firewall and applies any rules that have been configured at startup. + ```shell -sudo csf -ra +sudo csf -s ```
-Two **csf.conf** configuration files have been provided as examples; a full version, and clean (uncommented) version, and can be viewed on the [csf.conf](./conf.md) page. +### Restart + + +Restart firewall rules (csf) + +```shell +sudo csf -r +``` + +
+ +A full list of CSF commands have been provided in our [Cheatsheet: Commands](../../cheatsheet/commands/) section. + +
+ +--- + +
+ +## Next Steps + +```embed +url: ../webui +name: Next: Installing the Admin WebUI +desc: Instructions for installing the CSF Admin Web Interface +image: https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSjXOa4WN-mW3gXnIo_hEY6uAwoi2v_e02eG3TCHxSwIY70Y_OzErdaeaepXFoRa2sYx8M&usqp=CAU +favicon: https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSjXOa4WN-mW3gXnIo_hEY6uAwoi2v_e02eG3TCHxSwIY70Y_OzErdaeaepXFoRa2sYx8M&usqp=CAU +favicon_size: 25 +target: same +accent: a40547E0 +```
diff --git a/docs/docs/csf/install.md b/docs/docs/csf/install.md new file mode 100644 index 000000000..f53ceb8f7 --- /dev/null +++ b/docs/docs/csf/install.md @@ -0,0 +1,138 @@ +--- +title: Install CSF +tags: + - install +--- + +# Install CSF +These steps explain how to install ConfigServer Firewall on your system. There are two possible ways to install CSF which are listed below: + +- [Install: Using Patch](#install-using-patch) +- [Install: Manually](#install-manually) +- [Next Steps](#next-steps) + +
+ +The [Patch](#install-using-patch) method attempts to take much of the work out of installing CSF. It installs all prerequisites automatically, and sets CSF to start with `TESTING MODE` disabled. After CSF is installed using the patcher; then the Docker and OpenVPN patches will automatically be installed next. + +The [Manual](#install-manually) method requires you to manually install all prerequisites using your OS package manager, and then manually downloading the latest copy of CSF and extracting / installing it on your system. You will have to run the patcher after you have installed CSF. + +
+ +--- + +
+ +## Install: Using Patch + +If you would like to install ConfigServer Firewall using this repo's patcher; download the patch: +```shell +git clone https://github.com/Aetherinox/csf-firewall.git +``` + +
+ +Set the permissions for the `install.sh` file: +```shell +sudo chmod +x /csf-firewall/patch/install.sh +``` + +
+ +Run the script: +```shell +sudo ./csf-firewall/patch/install.sh +``` + +
+ +If ConfigServer Firewall is not already installed on your system; you should see: +``` + Installing package iptables + Installing package ipset + Installing package ConfigServer Firewall + + Patch installer will now start ... +``` + +
+ +After the patcher has installed CSF; it will then automatically install the Docker and OpenVPN patches. All you will need to do after; is ensure CSF is up and running. + +Please proceed to the section [Configure & Start CSF](../../configure/start/) + +
+ +--- + +
+ +## Install: Manually + +### Prerequisites +- A Linux server running CentOS, Debian, Ubuntu, or any other compatible Linux distribution. +- Root access or a user account with sudo privileges. +- Perl installed on your server. If Perl is not installed, you can install it by running the following commands: + - For **CentOS/RHEL**: + ```shell + sudo yum install perl ipset + ``` + + - For **Debian/Ubuntu**: + + ```shell + sudo apt-get update + sudo apt-get install perl ipset + ``` + +
+ +### Download and Install CSF +To download and install CSF, follow these steps: + +- Log in to your server via SSH. +- Download the latest version of CSF using the wget command: + ```shell + wget https://download.configserver.com/csf.tgz + ``` +- Extract the downloaded archive: + ```shell + tar -xzf csf.tgz + ``` +- Navigate to the extracted directory: + ```shell + cd csf + ``` +- Run the installation script: + ```shell + sudo sh install.sh + ``` + +
+ +CSF will now be installed on your server, along with its Web UI (ConfigServer Firewall & Security) if you have a control panel like cPanel or DirectAdmin installed. + +
+ +--- + +
+ +## Next Steps + +```embed +url: ../configure +name: Next: How to Configure & Start CSF +desc: Instructions for editing the CSF config file and starting CSF for the first time +image: https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSjXOa4WN-mW3gXnIo_hEY6uAwoi2v_e02eG3TCHxSwIY70Y_OzErdaeaepXFoRa2sYx8M&usqp=CAU +favicon: https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSjXOa4WN-mW3gXnIo_hEY6uAwoi2v_e02eG3TCHxSwIY70Y_OzErdaeaepXFoRa2sYx8M&usqp=CAU +favicon_size: 25 +target: same +accent: a40547E0 +``` + +
+ +--- + +
diff --git a/docs/docs/csf_install/testing.md b/docs/docs/csf/testing.md similarity index 100% rename from docs/docs/csf_install/testing.md rename to docs/docs/csf/testing.md diff --git a/docs/docs/csf/uninstall.md b/docs/docs/csf/uninstall.md new file mode 100644 index 000000000..279cf4387 --- /dev/null +++ b/docs/docs/csf/uninstall.md @@ -0,0 +1,27 @@ +--- +title: Uninstall CSF +tags: + - install +--- + +# Uninstall CSF +If you decide to uninstall CSF for any reason, follow these steps: + +1. Navigate to the CSF directory: + ```shell + cd /etc/csf + ``` +2. Run the uninstallation script: + ```shell + sudo sh uninstall.sh + ``` + +
+ +The script will remove CSF and its associated files from your server. + +
+ +--- + +
diff --git a/docs/docs/csf/webui.md b/docs/docs/csf/webui.md new file mode 100644 index 000000000..1b7e14ed9 --- /dev/null +++ b/docs/docs/csf/webui.md @@ -0,0 +1,196 @@ +--- +title: Install WebUI +tags: + - install +--- + +# Install WebUI +ConfigServer Firewall offers a WebUI for the managing firewall from the web interface. This section explains how to install the WebUI. + +
+ +### Step 1: Install Required Perl Modules: +The CSF WebUI requires a few Perl modules to be installed on your system. Use the following commands to install the required modules as per your operating system. + +
+ +**Debian based systems:** +```shell +sudo apt-get install libio-socket-ssl-perl libcrypt-ssleay-perl \ + libnet-libidn-perl libio-socket-inet6-perl libsocket6-perl +``` + +
+ +**Redhat based systems:** +```shell +sudo yum install perl-IO-Socket-SSL.noarch perl-Net-SSLeay perl-Net-LibIDN \ + perl-IO-Socket-INET6 perl-Socket6 +``` + +
+ +### Step 2: Enable CSF Firewall Web UI: +To enable CSF web UI edit /etc/csf/csf.conf file in your favorite text editor and update the following values. + +```shell +sudo vim /etc/csf/csf.conf +``` + +```conf +# 1 to enable, 0 to disable web ui +UI = "1" + +# Set port for web UI. The default port is 6666, but +# I change this to 1025 to easy access. Default port create some issue +# with popular chrome and firefox browser (in my case) + +UI_PORT = "1025" + +# Leave blank to bind to all IP addresses on the server +UI_IP = "" + +# Set username for authetnication +UI_USER = "admin" + +# Set a strong password for authetnication +UI_PASS = "admin" +``` + +
+ +Change the following values to your own: + +- `UI_PORT` +- `UI_USER` +- `UI_PASS` + +
+ +After making changes, edit `/etc/csf/ui/ui.allow` configuration file and add your public IP to allow access to CSF UI. Change `YOUR_PUBLIC_IP_ADDRESS` with your public IP address. + +```shell +sudo echo "YOUR_PUBLIC_IP_ADDRESS" >> /etc/csf/ui/ui.allow +``` + +
+ +Web UI works under lfd daemon. So restart the lfd daemon on your system using the following command. + +```shell +sudo service lfd restart +``` + +
+ +In order to gain access to the online admin panel; you must ensure lfd and csf are running. You can check by running the command: + +```shell +sudo service lfd status +``` + +
+ +You should see the `lfd` service running: + +``` +● lfd.service - ConfigServer Firewall & Security - lfd + Loaded: loaded (/lib/systemd/system/lfd.service; enabled; preset: enabled) + Active: active (running) since Mon 2024-08-05 11:59:38 MST; 1s ago + Process: 46393 ExecStart=/usr/sbin/lfd (code=exited, status=0/SUCCESS) + Main PID: 46407 (lfd - sleeping) + Tasks: 8 (limit: 4613) + Memory: 121.7M + CPU: 2.180s + CGroup: /system.slice/lfd.service +``` + +
+ +Next, confirm `csf` service is also running: + +```shell +sudo service csf status +``` + +
+ +Check the output for errors on service `csf`. You should see no errors: + +``` +● csf.service - ConfigServer Firewall & Security - csf + Loaded: loaded (/lib/systemd/system/csf.service; enabled; preset: enabled) + Active: active (exited) since Mon 2024-08-05 12:04:09 MST; 1s ago + Process: 46916 ExecStart=/usr/sbin/csf --initup (code=exited, status=0/SUCCESS) + Main PID: 46916 (code=exited, status=0/SUCCESS) + CPU: 12.692s +``` + +
+ +If you see the following error when running `csf status`: + +``` +csf[46313]: open3: exec of /sbin/ipset flush failed: No such file or directory at /usr/sbin/csf line 5650. +``` + +
+ +You must install `ipset`: + +```shell +sudo apt-get update +sudo apt-get install ipset +``` + +
+ +### Step 3: Access and Use Web UI: +Now, access CSF UI on your browser with the specified port. For this tutorial; we used 1025 port and accessed the CSF admin panel by opening our browser and going to: + +``` +https://127.0.0.1:1025 +``` + +
+ +When prompted for the username and password; the default is: + +| Field | Value | +| --- | --- | +| Username | `admin` | +| Password | `admin` | + +
+ +

+ +
+ +After successful login, you will find the screen like below. + +

+ +
+ +**Allow IP Address**: You can use below option to allow any IP quickly. This action adds the entry to the `/etc/csf/csf.allow` file. + +

+ +
+ +**Deny IP Address**: You can use below option to deny any IP quickly. This action adds the entry to the `/etc/csf/csf.deny` file. + +

+ +
+ +**Unblock IP Address**: You can use below option to quickly unblocked any IP which is already blocked by CSF. + +

+ +
+ +--- + +
diff --git a/docs/docs/csf_install/using_manual.md b/docs/docs/csf_install/using_manual.md deleted file mode 100644 index 8eac6421e..000000000 --- a/docs/docs/csf_install/using_manual.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Install CSF > Using Manual Mode -tags: - - install ---- - -# Install CSF: Using Patch - -These steps explain how to install ConfigServer Firewall manually using a direct download of ConfigServer Firewall. - -
- -#### Step 1: Prerequisites -- A Linux server running CentOS, Debian, Ubuntu, or any other compatible Linux distribution. -- Root access or a user account with sudo privileges. -- Perl installed on your server. If Perl is not installed, you can install it by running the following commands: - - For **CentOS/RHEL**: - ```shell - sudo yum install perl ipset - ``` - - - For **Debian/Ubuntu**: - - ```shell - sudo apt-get update - sudo apt-get install perl ipset - ``` - -
- -#### Step 2: Download and Install CSF -To download and install CSF, follow these steps: - -- Log in to your server via SSH. -- Download the latest version of CSF using the wget command: - ```shell - wget https://download.configserver.com/csf.tgz - ``` -- Extract the downloaded archive: - ```shell - tar -xzf csf.tgz - ``` -- Navigate to the extracted directory: - ```shell - cd csf - ``` -- Run the installation script: - ```shell - sudo sh install.sh - ``` - -
- -CSF will now be installed on your server, along with its Web UI (ConfigServer Firewall & Security) if you have a control panel like cPanel or DirectAdmin installed. - -
- ---- - -
diff --git a/docs/docs/csf_install/using_patch.md b/docs/docs/csf_install/using_patch.md deleted file mode 100644 index c596b5696..000000000 --- a/docs/docs/csf_install/using_patch.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Install CSF > Using Patch -tags: - - install ---- - -# Install CSF: Manually - -If you would like to install ConfigServer Firewall using this repo's patcher; download the patch: -```shell -git clone https://github.com/Aetherinox/csf-firewall.git -``` - -
- -Set the permissions for the `install.sh` file: -```shell -sudo chmod +x /csf-firewall/patch/install.sh -``` - -
- -Run the script: -```shell -sudo ./csf-firewall/patch/install.sh -``` - -
- -If ConfigServer Firewall is not already installed on your system; you should see: -``` - Installing package iptables - Installing package ipset - Installing package ConfigServer Firewall - - Docker patch will now start ... -``` - -
- ---- - -
diff --git a/docs/docs/manage/start.md b/docs/docs/manage/start.md deleted file mode 100644 index 0b990d714..000000000 --- a/docs/docs/manage/start.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Manage: Enable % Start" -tags: - - manage ---- - -# Manage: Enable & Start CSF -After you have installed CSF and configured the `csf.conf` file; it is time to get CSF running. - -CSF includes **enable** and **start** commands which can be executed from your Terminal by running: - -```shell -# enable (-e, --enable) -sudo csf -e - -# start (-s, --start) -sudo csf -s -``` - -
- ---- - -
diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css index 0bf96bd9b..73caae24b 100644 --- a/docs/docs/stylesheets/extra.css +++ b/docs/docs/stylesheets/extra.css @@ -488,15 +488,89 @@ } +/* + Badge > Header Padding + if a badge is used in a header, add padding between the badge and text +*/ + +:is(h1, h2, h3, h4, h5, h6) .mdx-badge__icon +{ + margin-inline-end: 6px; +} + +/* + Navigation > Spacer + Add a gap between the last "File" item in nav menu, and the folders under. +*/ + +li:has(a[href*="about_patcher"]) +{ + margin-bottom: 28px !important; +} + +/* + Navigation > Active Group Spacer + adds a small spacer between each group of items opened. + + issue with this is that it makes animations choppy. + the only way to fix this; is to disable the transition. + (see the next two rules) +*/ + +& li.md-nav__item--nested > nav.md-nav[aria-expanded="true"] +{ + padding-bottom: 10px; +} + +.md-nav__toggle ~ .md-nav +{ + -webkit-transition: none !important; + -moz-transition: none !important; + -o-transition: none !important; + transition: none !important; +} + +.md-nav__toggle.md-toggle--indeterminate ~ .md-nav, .md-nav__toggle:checked ~ .md-nav +{ + -webkit-transition: none !important; + -moz-transition: none !important; + -o-transition: none !important; + transition: none !important; +} + +/* + Badge > Header Positioning + This is mainly for the conventions page +*/ + +h2:has(.mdx-badge) > .mdx-badge > span +{ + padding-bottom: 2px; +} + +h2:has(.mdx-badge) > .mdx-badge svg +{ + margin-bottom: 2px; +} + +/* + Reposition badge icons in header +*/ + +:is(h1, h2, h3, h4, h5, h6) .mdx-badge__icon svg +{ + padding-top: 3px !important; + padding-right: 1px; +} + .md-typeset .mdx-badge a[title^="Requires"] svg, .md-typeset .mdx-badge a[title^="Default"] svg { - padding-top: 2px; - padding-left: 4px; + } .md-typeset .mdx-badge a[title^="Type"] svg { - padding: 2px; + } .mdx-badge__text a diff --git a/docs/material/overrides/hooks/shortcodes.py b/docs/material/overrides/hooks/shortcodes.py index a839618a6..172626ab5 100644 --- a/docs/material/overrides/hooks/shortcodes.py +++ b/docs/material/overrides/hooks/shortcodes.py @@ -1,22 +1,43 @@ -# Copyright (c) 2024 Aetherinox - -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to -# deal in the Software without restriction, including without limitation the -# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -# sell copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: - -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. - -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS -# IN THE SOFTWARE. +# # +# Copyright (c) 2024 Aetherinox +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to +# deal in the Software without restriction, including without limitation the +# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +# sell copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# # + +# # +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# # from __future__ import annotations @@ -28,11 +49,10 @@ from mkdocs.structure.pages import Page from re import Match -# ----------------------------------------------------------------------------- -# Hooks -# ----------------------------------------------------------------------------- +# # +# Hooks > on_page_markdown +# # -# @todo def on_page_markdown( markdown: str, *, page: Page, config: MkDocsConfig, files: Files ): @@ -41,32 +61,33 @@ def on_page_markdown( def replace(match: Match): type, args = match.groups() args = args.strip() + if type == "version": if args.startswith( "beta-" ): - return version_beta(args, page, files) + return Version_Beta(args, page, files) elif args.startswith( "stable-" ): - return version_stable( args, page, files ) + return Version_Stable( args, page, files ) else: - return version( args, page, files ) - - #elif type == "sponsors": return _badge_for_sponsors(page, files) - elif type == "color": return flag(args, page, files) - elif type == "control": return control(args, page, files) - elif type == "flag": return flag(args, page, files) - elif type == "option": return option(args) - elif type == "setting": return setting(args) - elif type == "feature": return _badge_for_feature(args, page, files) - elif type == "plugin": return _badge_for_plugin(args, page, files) - elif type == "extension": return _badge_for_extension(args, page, files) - elif type == "utility": return _badge_for_utility(args, page, files) - elif type == "example": return _badge_for_example(args, page, files) + return Version( args, page, files ) + + elif type == "backers": return Badge_Backers(page, files) + elif type == "control": return Create_Control(args, page, files) + elif type == "flag": return Create_Flag(args, page, files) + elif type == "option": return Create_Option(args) + elif type == "setting": return Create_Setting(args) + elif type == "command": return Badge_Command(args, page, files) + elif type == "feature": return Badge_Feature(args, page, files) + elif type == "plugin": return Badge_Plugin(args, page, files) + elif type == "extension": return Badge_Extension(args, page, files) + elif type == "3rdparty": return Badge_3rdparty(args, page, files) + elif type == "example": return Badge_Example(args, page, files) elif type == "default": - if args == "none": return _badge_for_default_none(page, files) - elif args == "computed": return _badge_for_default_computed(page, files) - else: return _badge_for_default(args, page, files) + if args == "none": return Badge_DefaultValue_None(page, files) + elif args == "computed": return Badge_DefaultValue_Computed(page, files) + else: return Badge_DefaultValue_Custom(args, page, files) # Otherwise, raise an error - raise RuntimeError(f"Unknown shortcode: {type}") + raise RuntimeError( f"Error in shortcodes.yp - Specified an unknown shortcode: {type}" ) # Find and replace all external asset URLs in current page return re.sub( @@ -74,26 +95,24 @@ def replace(match: Match): replace, markdown, flags = re.I | re.M ) -# ----------------------------------------------------------------------------- -# Helper functions -# ----------------------------------------------------------------------------- +# # +# Create > Flag +# # -# Create a flag of a specific type -def flag(args: str, page: Page, files: Files): +def Create_Flag(args: str, page: Page, files: Files): type, *_ = args.split(" ", 1) - if type == "experimental": return _badge_for_experimental(page, files) - elif type == "required": return _badge_for_required(page, files) - elif type == "customization": return _badge_for_customization(page, files) - elif type == "metadata": return _badge_for_metadata(page, files) - elif type == "multiple": return _badge_for_multiple(page, files) + if type == "experimental": return Badge_Flag_Experimental(page, files) + elif type == "required": return Badge_Flag_Required(page, files) + elif type == "customization": return Badge_Flag_Customization(page, files) + elif type == "metadata": return Badge_Flag_Metadata(page, files) + elif type == "multiple": return Badge_Multiple_Instances(page, files) raise RuntimeError(f"Unknown type: {type}") -# ----------------------------------------------------------------------------- -# Control Type -# ----------------------------------------------------------------------------- +# # +# Create > Controls +# # -# Create a flag of a specific type -def control( args: str, page: Page, files: Files ): +def Create_Control( args: str, page: Page, files: Files ): type, *_ = args.split( " ", 2 ) if type == "toggle": return icon_control_toggle( page, files ) elif type == "toggle_on": return icon_control_toggle_on( page, files ) @@ -107,13 +126,19 @@ def control( args: str, page: Page, files: Files ): raise RuntimeError(f"Unknown type: {type}") -# Create a linkable option -def option(type: str): +# # +# Create > Option +# # + +def Create_Option(type: str): _, *_, name = re.split(r"[.:]", type) return f"[`{name}`](#+{type}){{ #+{type} }}\n\n" -# Create a linkable setting - @todo append them to the bottom of the page -def setting(type: str): +# # +# Create > Setting +# # + +def Create_Setting(type: str): _, *_, name = re.split(r"[.*]", type) return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n" @@ -134,8 +159,11 @@ def _resolve(file: File, page: Page): # ----------------------------------------------------------------------------- -# Create badge -def _badge(icon: str, text: str = "", type: str = ""): +# # +# Create > Badge +# # + +def Create_Badge(icon: str, text: str = "", type: str = ""): classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge" return "".join([ f"", @@ -144,13 +172,18 @@ def _badge(icon: str, text: str = "", type: str = ""): f"", ]) -def _badge_color(icon: str, text: str = "", type: str = ""): +# # +# Badge > Color Palette +# # + +def Badge_ColorPalette(icon: str, text: str = "", type: str = ""): args = type.split( " " ) bg1_clr = "#000000" bg2_clr = "#000000" bg1_dis = "none" bg2_dis = "none" + if len( args ) > 1: bg1_clr = args[ 1 ] bg1_dis = "inline-block" @@ -168,30 +201,53 @@ def _badge_color(icon: str, text: str = "", type: str = ""): f"  ", ]) -# Create sponsors badge -def _badge_for_sponsors(page: Page, files: Files): +# # +# Badge > Sponsor / Backers +# +# In order for the sponsor / backers badge to work, you must have a backers page created in your mkdocs. +# add a new file; usually about/backers.md +# create a new entry in your mkdocs.yml to add the page to your navigation +# +# use the following tag in your md files: +# __Sponsors only__ – this plugin is currently reserved to [our awesome sponsors]. +# +# # + +def Badge_Backers(page: Page, files: Files): icon = "material-heart" - href = _resolve_path("insiders/index.md", page, files) - return _badge( - icon = f"[:{icon}:]({href} 'Sponsors only')", + href = _resolve_path("about/backers.md", page, files) + return Create_Badge( + icon = f"[:{icon}:]({href} 'Backers only')", type = "heart" ) -# Create badge for version -def version( text: str, page: Page, files: Files ): +# # +# Badge > Version +# +# In order for the version badge to work, you must have a corresponding version entry in your changelog.md. +# if not, you will receive the console error `'NoneType' object has no attribute 'src_uri'` +# +# use the following tag in your md file: +# +# # + +def Version( text: str, page: Page, files: Files ): spec = text path = f"changelog.md#{spec}" # Return badge icon = "aetherx-axs-box" href = _resolve_path("about/conventions.md#version", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Proteus Release')", text = f"[{text}]({_resolve_path(path, page, files)})" if spec else "" ) -# Create badge for version of beta -def version_stable( text: str, page: Page, files: Files ): +# # +# Badge > Version > Stable +# # + +def Version_Stable( text: str, page: Page, files: Files ): spec = text.replace( "stable-", "" ) path = f"changelog.md#{spec}" @@ -206,13 +262,16 @@ def version_stable( text: str, page: Page, files: Files ): else: output = f"Stable Release" - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} '{output}' )", text = f"[{spec}]({_resolve_path(path, page, files)})" if spec else "" ) -# Create badge for version of beta -def version_beta( text: str, page: Page, files: Files ): +# # +# Badge > Version > Beta +# # + +def Version_Beta( text: str, page: Page, files: Files ): spec = text.replace( "beta-", "" ) path = f"changelog.md#{spec}" @@ -227,199 +286,393 @@ def version_beta( text: str, page: Page, files: Files ): else: output = f"Beta Release" - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} '{output}' )", text = f"[{text}]({_resolve_path(path, page, files)})" if spec else "" ) -# Create badge for feature -def _badge_for_feature(text: str, page: Page, files: Files): +# # +# Badge > Feature +# +# use the following tag in your md file: +# +# # + +def Badge_Feature(text: str, page: Page, files: Files): icon = "material-toggle-switch" href = _resolve_path("about/conventions.md#feature", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Optional feature')", text = text ) -# Create badge for plugin -def _badge_for_plugin(text: str, page: Page, files: Files): +# # +# Badge > Feature +# +# use the following tag in your md file: +# +# +# +# # + +def Badge_Plugin(text: str, page: Page, files: Files): icon = "material-floppy" href = _resolve_path("about/conventions.md#plugin", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Plugin')", text = text ) -# Create badge for extension -def _badge_for_extension(text: str, page: Page, files: Files): +# # +# Create badge for extension +# +# use the following tag in your md file: +# +# # + +def Badge_Extension(text: str, page: Page, files: Files): icon = "material-language-markdown" href = _resolve_path("about/conventions.md#extension", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Markdown extension')", text = text ) -# Create badge for utility -def _badge_for_utility(text: str, page: Page, files: Files): +# # +# Badge > Third Party Plugin / Utility +# +# This symbol denotes that the item described is classified as something that changes the overall functionality of the plugin. +# +# use the following tag in your md files: +# +# +# # + +def Badge_3rdparty(text: str, page: Page, files: Files): icon = "material-package-variant" - href = _resolve_path("about/conventions.md#utility", page, files) - return _badge( + href = _resolve_path("about/conventions.md#3rdparty", page, files) + return Create_Badge( icon = f"[:{icon}:]({href} 'Third-party utility')", text = text ) -# Create badge for example -def _badge_for_example(text: str, page: Page, files: Files): +# # +# Create Download Example > View +# +# Creates a badge which allows a user to download a file. +# +# The badge will have three sections: +# - View Example +# - Download Example +# - .zip text +# +# If you supply the code below with a title of `my-example-file`, the links generated will be: +# - [View Example] https://github.com/Aetherinox/csf-firewall/my-example-file/ +# - [Download Example] https://github.com/Aetherinox/csf-firewall/my-example-file.zip +# - [Zip] https://github.com/Aetherinox/csf-firewall/my-example-file.zip +# +# use the following tag in your md files: +# +# # + +def Badge_Example(text: str, page: Page, files: Files): return "\n".join([ - _badge_for_example_download(text, page, files), - _badge_for_example_view(text, page, files) + Badge_Example_Download_Zip(text, page, files), + Badge_Example_View(text, page, files) ]) -# Create badge for example view -def _badge_for_example_view(text: str, page: Page, files: Files): +def Badge_Example_View(text: str, page: Page, files: Files): icon = "material-folder-eye" - href = f"https://mkdocs-material.github.io/examples/{text}/" - return _badge( + href = f"https://github.com/Aetherinox/csf-firewall/{text}/" + return Create_Badge( icon = f"[:{icon}:]({href} 'View example')", type = "right" ) -# Create badge for example download -def _badge_for_example_download(text: str, page: Page, files: Files): +def Badge_Example_Download_Zip(text: str, page: Page, files: Files): icon = "material-folder-download" - href = f"https://mkdocs-material.github.io/examples/{text}.zip" - return _badge( + href = f"https://github.com/Aetherinox/csf-firewall/{text}.zip" + return Create_Badge( icon = f"[:{icon}:]({href} 'Download example')", text = f"[`.zip`]({href})", type = "right" ) -# Create badge for default value -def _badge_for_default(text: str, page: Page, files: Files): +# # +# Badge > Command +# +# Used when specifying a command in an app +# +# use the following tag in your md file: +# +# # + +def Badge_Command(text: str, page: Page, files: Files): + icon = "material-console-line" + href = _resolve_path("about/conventions.md#command", page, files) + return Create_Badge( + icon = f"[:{icon}:]({href} 'Terminal / Console Command')", + text = text + ) + +# # +# Badge > Default Value > Custom +# +# This defines what the default value for a setting is. +# +# use the following tag in your md file: +# +# +# +# +# # + +def Badge_DefaultValue_Custom(text: str, page: Page, files: Files): icon = "material-water" href = _resolve_path("about/conventions.md#default", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Default value')", text = text ) -# Create badge for empty default value -def _badge_for_default_none(page: Page, files: Files): +# # +# Badge > Default Value > None / Empty +# +# This defines what the default value for a setting is. +# +# use the following tag in your md file: +# +# +# +# +# # + +def Badge_DefaultValue_None(page: Page, files: Files): icon = "material-water-outline" href = _resolve_path("about/conventions.md#default", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Default value is empty')" ) -# Create badge for computed default value -def _badge_for_default_computed(page: Page, files: Files): +# # +# Badge > Default Value > Computed +# +# This defines what the default value for a setting is. +# +# use the following tag in your md file: +# +# +# +# +# # + +def Badge_DefaultValue_Computed(page: Page, files: Files): icon = "material-water-check" href = _resolve_path("about/conventions.md#default", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Default value is computed')" ) -# Create badge for metadata property flag -def _badge_for_metadata(page: Page, files: Files): +# # +# Badge > Flag > Metadata Property +# +# This symbol denotes that the item described is a metadata property, which can +# be used in Markdown documents as part of the front matter definition. +# +# use the following tag in your md file: +# +# # + +def Badge_Flag_Metadata(page: Page, files: Files): icon = "material-list-box-outline" href = _resolve_path("about/conventions.md#metadata", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Metadata property')" ) -# Create badge for required value flag -def _badge_for_required(page: Page, files: Files): +# # +# Badge > Flag > Required +# +# Specifies that a value is required. +# +# use the following tag in your md file: +# +# This option enables the content tabs +# # + +def Badge_Flag_Required(page: Page, files: Files): icon = "material-alert" href = _resolve_path("about/conventions.md#required", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Required value')" ) -# Create badge for customization flag -def _badge_for_customization(page: Page, files: Files): +# # +# Badge > Flag > Customization +# +# This symbol denotes that the item described is a customization which affects the overall look of the app. +# +# use the following tag in your md file: +# +# # + +def Badge_Flag_Customization(page: Page, files: Files): icon = "material-brush-variant" href = _resolve_path("about/conventions.md#customization", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Customization')" ) -# Create badge for experimental flag -def _badge_for_experimental(page: Page, files: Files): +# # +# Badge > Flag > Experimental +# +# This symbol denotes that the item described is Experimental +# +# MUST add an entry in conventions.md +# +# use the following tag in your md file: +# +# # + +def Badge_Flag_Experimental(page: Page, files: Files): icon = "material-flask-outline" href = _resolve_path("about/conventions.md#experimental", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Experimental')" ) -# Icon : Control : Textbox +# # +# Badge > Flag > Multiple Instances +# +# This symbol denotes that the plugin supports multiple instances, i.e, that it +# can be used multiple times in the `plugins` setting +# +# MUST add an entry in conventions.md +# +# use the following tag in your md file: +# +# # + +def Badge_Multiple_Instances(page: Page, files: Files): + icon = "material-inbox-multiple" + href = _resolve_path("about/conventions.md#multiple-instances", page, files) + return Create_Badge( + icon = f"[:{icon}:]({href} 'Multiple instances')" + ) + +# # +# Icon : Control : Default +# +# This function is activated if no control type specified +# +# use the following tag in your md file: +# +# # + def icon_control_default( page: Page, files: Files ): icon = "aetherx-axs-hand-pointer" href = _resolve_path( "about/conventions.md#control", page, files ) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Type: Textbox')" ) -# Icon : Control : Textbox +# # +# Icon : Control : Textbox +# +# use the following tag in your md file: +# +# # + def icon_control_textbox( page: Page, files: Files ): icon = "aetherx-axs-input-text" href = _resolve_path( "about/conventions.md#control", page, files ) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Type: Textbox')" ) -# Icon : Control : Toggle Switch +# # +# Icon : Control : Toggle Switch +# +# use the following tag in your md file: +# +# `Enabled` +# `Disabled` +# # + def icon_control_toggle( page: Page, files: Files ): icon = "aetherx-axs-toggle-large-on" href = _resolve_path("about/conventions.md#control", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Type: Toggle Switch')" ) -# Icon : Control : Toggle Switch > Enabled def icon_control_toggle_on( page: Page, files: Files ): icon = "aetherx-axd-toggle-on" href = _resolve_path("about/conventions.md#control", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Toggle: Enabled')" ) -# Icon : Control : Toggle Switch > Disabled def icon_control_toggle_off( page: Page, files: Files ): icon = "aetherx-axd-toggle-off" href = _resolve_path("about/conventions.md#control", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Toggle: Disabled')" ) -# Icon : Control : Dropdown +# # +# Icon : Control : Dropdown +# +# use the following tag in your md file: +# +# # + def icon_control_dropdown( page: Page, files: Files ): icon = "aetherx-axs-square-caret-down" href = _resolve_path("about/conventions.md#control", page, files) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Type: Dropdown')" ) -# Icon : Control : Button +# # +# Icon : Control : Button +# +# use the following tag in your md file: +# +# # + def icon_control_button( page: Page, files: Files ): icon = "material-button-pointer" href = _resolve_path( "about/conventions.md#control", page, files ) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Type: Button')" ) -# Icon : Control : Slider +# # +# Icon : Control : Slider +# +# use the following tag in your md file: +# +# # + def icon_control_slider( page: Page, files: Files ): icon = "aetherx-axd-sliders-simple" href = _resolve_path( "about/conventions.md#control", page, files ) - return _badge( + return Create_Badge( icon = f"[:{icon}:]({href} 'Type: Slider')" ) -# Icon : Control : Color +# # +# Icon : Control : Color +# +# use the following tag in your md file: +# +# # + def icon_control_color( text: str, page: Page, files: Files ): icon = "aetherx-axs-palette" href = _resolve_path( "about/conventions.md#control", page, files ) - return _badge_color( + return Badge_ColorPalette( icon = f"[:{icon}:]({href} 'Type: Color Wheel')", type = text ) \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index d5a630b20..39d1ae78e 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -154,20 +154,23 @@ nav: - Home: 'home.md' - About CSF: 'about_csf.md' - About Patcher: 'about_patcher.md' - - CSF - Install: - - Using Patch: 'csf_install/using_patch.md' - - Using Manual Mode: 'csf_install/using_manual.md' - - Test Install: 'csf_install/testing.md' - - CSF - Configure: - - Basics: 'configure/basics.md' - - csf.conf: 'configure/conf.md' - - CSF - Manage: - - Enable & Start: 'manage/start.md' + - Cheatsheet: + - Structure: 'cheatsheet/structure.md' + - Commands: 'cheatsheet/commands.md' + - Troubleshooting: 'cheatsheet/troubleshooting.md' + - Example csf.conf: 'cheatsheet/conf.md' + - ConfigServer Firewall: + - Install: 'csf/install.md' + - Configure: 'csf/configure.md' + - Install WebUI: 'csf/webui.md' + - Test Install: 'csf/testing.md' + - Uninstall: 'csf/uninstall.md' - About: - License: 'about/license.md' - Conventions: 'about/conventions.md' - Tags: 'about/tags.md' - Changelog: 'about/changelog.md' + - Backers: 'backers/index.md' plugins: - search: @@ -244,7 +247,7 @@ plugins: image_default: "https://github.com/Aetherinox/mkdocs-link-embeds/assets/118329232/c0298d98-0910-4235-a88f-0c3e2f704ba7" image_disabled: false favicon_default: "https://github.com/Aetherinox/mkdocs-link-embeds/assets/118329232/b37da9c6-6f17-4c3f-9c94-c346a6f31bfa" - favicon_disabled: false + favicon_disabled: true favicon_size: 25 target: "blank" accent: "FFFFFF1A"