Skip to content

Commit

Permalink
Backport some of Zack's PRs to 3.0 branch (#3139)
Browse files Browse the repository at this point in the history 
* Backport some of Zack's PRs to 3.0 branch

Review and compress images
Do a little copyediting here and there

* Update IPv6.md

reword line 21 to remove possessive case

* Update words-to-ignore.txt

* Update words-to-ignore.txt

---------

Co-authored-by: MicJ <[email protected]>
Co-authored-by: MicJ <[email protected]>
  • Loading branch information
@Mrt134 @micjohnson777
3 people authored Oct 18, 2024
1 parent cd088c1 commit 77bac5b
Show file tree
Hide file tree
Showing 27 changed files with 351 additions and 158 deletions.
35 changes: 32 additions & 3 deletions content/AdminGuide/Admin/LDAPServers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,14 @@ Click the gear icon in the upper toolbar and select **Administration**. Scroll d
|---------|-------------|
| **Hostname** | Host name of LDAP/AD server, with optional port. e.g. example.com:636. |
| **Domain** | LDAP base domain. e.g. dc=example,dc=com. |
| **Group Domain** | Optional for admins that want to avoid issues with unwanted groups by forcing group searches to start at a deeper domain. |
| **Group Search Domain** | Optional for admins who want to avoid issues with unwanted groups by forcing group searches to start at a deeper domain. |
| **User ID Field** | Class mapped to login username. The default is uid. |
| **Group ID Field** | Class for finding groups associated with a user. The default is cn. |
| **BIND User Domain** | Full user domain for binding before finding user fully qualified ID (FQID). Optional. |
| **BIND Password** | If the bind user is set, use this password when performing a simple bind on user search. |
| **Realm** | The realm that performs authentication against the LDAP server. |
| **BIND Password** | If bind user is set, use this password when performing a simple bind on user search. |
| **KDC** | The Kerberos Key Distribution Center that supplies session tickets and temporary session keys to users and computers within the LDAP server. |
| **Enable SSL** | Enable LDAPS/TLS connection. Uses the globally configured verification settings. |
{{< /truetable >}}

After you fill the form according to your server, click **ADD SERVER**.
Expand All @@ -35,7 +36,8 @@ Click **CONFIGURE** in the **Configuration** widget and enable **Allow LDAP user

## Updating the LDAP Server

TrueCommand only checks for usernames and passwords when authenticating LDAP credentials. You may add entries for email, phone number, or URLs, but TrueCommand does not check for them.
TrueCommand only checks for usernames, passwords, and groups while authenticating LDAP credentials.
You can add entries for email, phone number, or URLs, but TrueCommand does not check for them.

The LDAP server uses an LDAP Data Interchange Format (LDIF) file to add or modify entries in the server.

Expand Down Expand Up @@ -67,3 +69,30 @@ changetype: modify
add: password
password: [email protected]
```

### LDAP Groups

For finding associated groups, TrueCommand looks for `groupOfUniqueNames`, `groupOfNames`, `posixGroup`, and `Group` object classes and users matching the `uniquemember`, `member`, `owner`, or `memberUid` attributes.

Teams configured under **LDAP Default Teams** are added to new users automatically, while group names can be mapped to one or more teams under **LDAP Group Mappings**.

![AddLDAPDefault](/images/TrueCommand/Administration/AddLDAPDefault.png "Add Default Teams")

![AddLDAPGroup](/images/TrueCommand/Administration/AddLDAPGroup.png "Add LDAP Group")

![AddLDAPGroupToTeam](/images/TrueCommand/Administration/AddLDAPGroupToTeam.png "Tie LDAP Group to Team")

### Troubleshooting

The two most prominent error codes for LDAP are 254 (connection failure) and 49 (invalid credentials).
In the event of a connection failure, ensure **Enable SSL** is set when only LDAPS is available.

For credential failures, ensure the right authentication mode, either BIND Password or Kerberos, is enabled.
When Kerberos is enabled, its use is preferred.

When password servers are required, move the autogenerated **krb5.conf** within the container from `/etc/krb5.conf` to `/data` and enable its use by setting `--env KRB5_CONFIG=/data/krb5.conf` on a new container run.
See the Middleware log for further debugging.
Some AD servers require manual SASL settings to avoid an "illegal packet length" error by setting the environment variable `--env LDAPSASL_SECPROPS=minssf=0,maxssf=0` to disable security factor limitations.
Other **ldap.conf** settings can be configured this way, or setting the LDAPCONF environment variable to `/data/ldap.conf` and writing a custom conf there.

TrueCommand sets `TLS_REQCERT` and `TLS_REQSAN` to **allow** or **demand** depending on global TLS settings, as well as TLS_CERT and TLS_KEY to the MW managed self-signed certificate in `/data/truecommand`.
65 changes: 34 additions & 31 deletions content/AdminGuide/Admin/SAML/SAMLGA.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,13 @@ After you configure SAML in Google Admin, you configure and start the TrueComman

{{< trueimage src="/images/SAML/GAAddServiceProviderDetailsCropped.png" alt="GA Add Service Provider Details Cropped" id="GA Add Service Provider Details Cropped" >}}

a. Enter the TrueCommand login URL http://*IP:PORT*/saml/acs in the **ACS Url** field.
*IP:PORT* is your TrueCommand system IP and port address.
a. Enter the TrueCommand login URL `https://*IP:PORT*/saml/acs` in the **ACS Url** field.
*IP:PORT* is your TrueCommand system IP with HTTPS port.

b. Type any name you want into the **Entity ID** field (ex. truecommand-saml).
c. Type the https://*IP:PORT*/saml/helloURL into the **Start URL** field.
*IP:PORT* is your TrueCommand system IP and port address.

c. Type the `https://*IP:PORT*/saml/hello` into the **Start URL** field.
*IP:PORT* is your TrueCommand system IP with HTTPS port.

d. Set **Name ID** format to **PERSISTENT**.

Expand All @@ -76,54 +76,57 @@ After you configure SAML in Google Admin, you configure and start the TrueComman
{{< truetable >}}
| Parameter | Value |
|-----------|-------|
| E-Mail-Addresses | email |
| Display-Name | given_name |
| User-Principal-Name | unique_name |
| Telephone-Number | telephoneNumber |
| Primary email | email |
| First name | given_name |
| Employee ID | unique_name |
| Phone number | telephone_number |
| Title | title |
{{< /truetable >}}
Adjust the parameters according to your own organization, where `unique_name` corresponds to the TrueCommand `username` and is the only required attribute.
`Primary email` might be desired instead of and if an `Employee ID` is not available.
h. Click **FINISH**.

5. Verify the information is correct.
5. Verify the information is correct.
Select **TEST SAML LOGIN** in the **tcsaml** area on the left side of the screen to open the **TrueCommand SAML Test** screen.

{{< trueimage src="/images/SAML/GAAddCustomSAMLAppTrueCommandSAMLTestCropped.png" alt="GA Add Custom SAML App TrueCommand SAML Test Cropped" id="GA Add Custom SAML App TrueCommand SAML Test Cropped" >}}

6. Download the metadata.

{{< trueimage src="/images/SAML/GAAddCustomSAMLAppDownloadMetaDataWindowCropped.png" alt="GA SAML App Download Metadata Cropped" id="GA SAML App Download Metadata Cropped" >}}
a. Select **DOWNLOAD METADATA** to open the **Download Metadata** window.

a. Select **DOWNLOAD METADATA** to open the **Download Metadata** window.

b. Click **DOWNLOAD METADATA** again. When complete, click **CLOSE**.
7. Verify user access details.

7. Verify user access details.

a. Click **View Details** under **User access** to display the **Service status** details.

{{< trueimage src="/images/SAML/GASAMLAppClickViewDetailsCropped.png" alt="GA SAML App Click View Details Cropped" id="GA SAML App Click View Details Cropped" >}}

b. Select **ON for everyone** and click **SAVE**.

{{< trueimage src="/images/SAML/GASAMLAppSetServiceStatusOnForEveryoneCropped.png" alt="GA SAML App Set Service Status On For Everyone Cropped" id="GA SAML App Set Service Status On For Everyone Cropped" >}}

If you want granular user control, use this area to set it.
8. Wait up for approximately 10-20 minutes for Google to populate all settings through its servers

8. Wait for approximately 10-20 minutes for Google to populate all settings through its servers.

## Configuring and Starting TrueCommand SAML Service

1. Log into TrueCommand as an administrator.

2. Click the <i class="material-icons" aria-hidden="true" title="Settings">settings</i> button on the top toolbar.
Click **Administration**. Click **Configure** in the **Configuration** widget.
The **Configuration** screen with the editable settings displays. Scroll down to **SAML settings**.
2. Click the <i class="material-icons" aria-hidden="true" title="Settings">settings</i> button on the top toolbar.
Click **Administration**. Click **Configure** in the **Configuration** widget.
The **Configuration** screen with the editable settings displays. Scroll down to **SAML settings**.

3. Enter the Google Admin XML metadata file into the **SAML Identity Provider Metadata XML Upload** field, then click **Save**.

5. Select **Start the SAML service** to enable the service, and click **Save** again.
4. Select **Start the SAML service** to enable the service, and click **Save** again.

6. Log out of TrueCommand UI.
5. Log out of the TrueCommand UI.

7. Login now using the **SAML Login** option.
6. Login now using the **SAML Login** option.
21 changes: 21 additions & 0 deletions content/Recommendations/IPv6.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
title: "TrueCommand IPv6 Configuration"
description: "Steps for enabling IPv6 communication between TrueCommand and a TrueNAS."
---

## Docker Host Setup

First, create a non-default network with IPv6 explicitly enabled:

```
joe@joe-minty:~$ docker network create --ipv6 NAME
joe@joe-minty:~$ docker run --network NAME --detach -v "/DockerDir:/data" -p 9004:80 -p 9005:443 ghcr.io/ixsystems/truecommand:latest
```

Linux hosts are also required for the Docker daemon to support IPv6.
The default bridge can be configured to support IPv6 if desired with a fixed address for dynamic allocation.

Configure both the host and NAS with IPv6 addresses, either through a dynamic protocol like SLAAC or by assigning a static IP, so the TrueCommand container has a route to the NAS.
Input the address, without URL brackets, when adding a new system or editing an existing system.

For more information, see <a href="https://docs.docker.com/config/daemon/ipv6/">guide to enable IPv6 support provided by Docker</a> and the [TrueNAS IPv6 setup document](https://www.truenas.com/docs/scale/scaletutorials/network/configureipv6/).
118 changes: 118 additions & 0 deletions content/Recommendations/Performance.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
---
title: "TrueCommand Performance Specification"
description: "Performance data for a self-hosted TrueCommand container."
---

### Base Usage

Without any connected systems, TrueCommand uses ~20 MiB memory and 600 KiB disk for the sqlite settings database and slightly more for logs.

{{< truetable >}}
| Resource | Usage |
|-----------|-------------|
|Memory | 20 MiB|
|Storage | < 1 MiB|
|Container | 1.1 GiB|
|Network | Nothing with UI closed, 10 KiB/min serving UI|
{{< /truetable >}}

### System Usage

TrueCommand scales for each system added.
Each connected TrueNAS uses the following resources:

{{< truetable >}}
|Resource | Usage|
|-----------|-------------|
|Memory | ~5-10 MiB|
|Storage | ~100 MiB|
|Disk | 1 MiB reads/hour, 4 MiB writes/hour|
|CPU | ~5s/hour, ~22ms/15s, 0.1 to 1.5%|
|Network | Rx 5-10 KiB/min<br>Tx < 1 KiB/min|
{{< /truetable >}}

Storage usage includes a fixed 80M MiB disk storage for metrics and 2 to 5 MiB for NAS configuration backups.
Backup retention and metric storage duration can be changed, although resizing metrics can result in larger files even after reversion.
Network transmitted bytes are very low for each system, as TrueCommand only sends requests to the NAS.
Typically the ratio of received bytes to transmitted is about 20:1.

## Methodology

cAdvisor, Prometheus, and Grafana were used to generate this data. See the following configuration files to reproduce.

### Prometheus Config

{{< highlight yaml "" >}}
global:
scrape_interval: 15s
evaluation_interval: 15s
# scrape_timeout is set to the global default (10s).

scrape_configs:
- job_name: docker
static_configs:
- targets: ["DOCKERHOST:8090"]
metrics_path: "/metrics"
params:
format: ['prometheus']
{{< /highlight >}}

This enables Prometheus to collect metrics about itself, the docker engine directly, if `metrics-addr` is configured for the daemon, and cAdvisor.
See the compose file below to configure the exposed port and provide a route from the Prometheus container to its sibling cAdvisor container.

### Compose Stack

{{< highlight yaml "" >}}
name: cadvisor_prometheus
services:
prometheus:
image: prom/prometheus:v2.53.1
volumes:
- type: bind
source: ./prometheus.yml
target: /etc/prometheus/prometheus.yml
read_only: true
ports:
- 9090:9090
grafana:
image: grafana/grafana-oss:11.0.1
volumes:
- type: volume
source: grafana-storage
target: /var/lib/grafana
ports:
- 3000:3000
cadvisor:
image: gcr.io/cadvisor/cadvisor:v0.47.2
volumes:
- type: bind
source: /
target: /rootfs
read_only: true
- type: bind
source: /var/run
target: /var/run
read_only: true
- type: bind
source: /var/lib/docker
target: /var/lib/docker
read_only: true
- type: bind
source: /sys
target: /sys
read_only: true
ports:
- 8090:8080
userns_mode: "host"
security_opt:
- seccomp=default.json
command: --docker=unix:///var/run/user/1000/docker.sock --listen_ip=0.0.0.0
volumes:
grafana-storage:
{{< /highlight >}}

Run `docker compose up` to deploy the three containers.
cAdvisor reads from the cgroup and reports container-level metrics to Prometheus.
Grafana can then be used to display these metrics, as seen in the following dashboard:

{{< trueimage src="/images/TrueCommand/tc-three-system-perf.png" alt="Grafana dashboard with TrueCommand running and connected to three TrueNAS systems" id="Grafana dashboard with TrueCommand running and connected to three TrueNAS systems" >}}
56 changes: 56 additions & 0 deletions content/Recommendations/Syslog.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: "TrueCommand Syslog Configuration"
description: "Steps for sending TrueCommand logs via the syslog protocol."
---

Remote logging capabilities through syslog are available in TrueCommand version 2.3 or later.

To enable, first edit the internal configuration file `/etc/config.yaml`.
Overwrite the TC_CONFIG_PATH or create an additional tied volume for this file to preserve changes.

{{< highlight yaml "" >}}
logger:
remote_log:
enabled: false
log_level: error
host: 127.0.0.1 # rsyslog server address
port: 6514 # port based on the protocol
protocol: tcp # tcp or udp
identifier: TrueCommand # will be added as tag in the logs
{{< / highlight >}}

Restart the container.

## Server Setup

An Rsyslog server can easily be setup with Docker.

### rsyslog.conf

```
$ModLoad imudp
$UDPServerRun 5514
$ModLoad imtcp
$InputTCPServerRun 6514
$template RemoteStore, "/var/log/remote/%$year%/%$Month%/%$Day%.log"
:source, !isequal, "localhost" -?RemoteStore
:source, isequal, "last" ~
```

### Dockerfile

{{< highlight yaml "" >}}
FROM ubuntu:latest
RUN apt update && apt install rsyslog -y
ADD rsyslog.conf /etc/.
ENTRYPOINT ["rsyslogd", "-n"]
{{< / highlight >}}

### Docker Build & Run

```
joe@joe-minty:~$ docker build -t rsyslog-server
joe@joe-minty:~$ docker run --rm -d -p 6514:6514 -p 5514:5514/udp --name rsyslog rsyslog-server
```

Logs are stored under the `/var/log/remote/YEAR/MONTH/DAY.log` path.
Loading

0 comments on commit 77bac5b

Please sign in to comment.