> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/gateway/de/getting-started/devolutions-gateway-configuration-on-linux.md). # Devolutions Gateway-Konfiguration unter Linux Installieren und konfigurieren Sie Devolutions Gateway unter Ubuntu Linux, einschließlich TLS-Zertifikaten, Firewall-Ports und der Verbindung mit Devolutions Server. Die Installation und Ausführung von Devolutions Gateway unter Linux ist schnell und einfach, sofern mehrere Voraussetzungen erfüllt sind. Ubuntu 22.04 LTS wurde verwendet, um die Installation und Konfiguration zu demonstrieren. {% hint style="warning" %} Für die Konfiguration sind Devolutions Server oder Devolutions Cloud sowie eine Devolutions Gateway-Lizenz erforderlich. {% endhint %} ### Devolutions Gateway installieren 1. Navigieren Sie zur Seite [Devolutions Gateway GitHub Release](https://github.com/Devolutions/devolutions-gateway/releases/) und laden Sie die **.deb**-Datei der neuesten Version herunter. 2. Geben Sie Folgendes über die Befehlszeile ein: `wget https://github.com/Devolutions/devolutions-gateway/releases/download/v2024.3.2/devolutions-gateway_2024.3.2.0_amd64.deb` 3. Installieren Sie das Paket mit dem Dienstprogramm `dpkg`: `sudo dpkg -i devolutions-gateway_2024.3.2.0_amd64.deb`

Die Konfigurations- und Binärpakete befinden sich an den folgenden Orten:

### Devolutions Gateway aktualisieren Um Devolutions Gateway unter Linux zu aktualisieren, laden Sie das neueste Paket wie im vorherigen Abschnitt beschrieben herunter und führen Sie den Installationsbefehl aus. Das Paket wird über die bestehende Installation installiert und behält die Konfigurationen bei. ### Das PowerShell-Gateway-Modul installieren Es wird empfohlen, das PowerShell-Gateway-Modul zu verwenden, um die Devolutions Gateway-Instanz unter Linux zu konfigurieren und zu verwalten. 1. Installieren Sie PowerShell mit diesem Befehl: ```powershell source /etc/os-release wget -q https://packages.microsoft.com/config/ubuntu/$VERSION_ID/packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb rm packages-microsoft-prod.deb sudo apt-get update sudo apt-get install -y powershell ``` 2. Installieren Sie das Devolutions Gateway PowerShell-Modul: ```powershell Install-Module -Name DevolutionsGateway Import-Module -Name DevolutionsGateway ``` Nach der Installation kann die Devolutions Gateway-Konfiguration gestartet, gestoppt, angezeigt oder geändert werden. ### Zertifikate konfigurieren Ein ordnungsgemäßes Vertrauen der Zertifikate zwischen Systemen ist entscheidend, damit Devolutions Gateway funktioniert. Funktionen wie WebSockets, die in Web-Dashboard-Ansichten von RDP, SSH usw. verwendet werden, erfordern ein ordnungsgemäß vertrauenswürdiges Zertifikat. Ein Zertifikat von einer offiziellen Stelle wie Let's Encrypt wäre für die meisten Produktionssysteme ideal. Selbstsignierte Zertifikate, wie im folgenden Beispiel gezeigt, können generiert werden, erfordern jedoch eine zusätzliche Konfiguration für das Vertrauen. Sie können Zertifikate auf jedem System generieren und in Devolutions Gateway verwenden, sofern sie den Zertifikatsanforderungen entsprechen. #### Ein LetsEncrypt-Zertifikat unter Ubuntu 22.04 LTS über Certbot generieren Eine Möglichkeit ist, ein LetsEncrypt-Zertifikat mit dem Dienstprogramm Certbot zu generieren. Um die neueste Version zu installieren, können Sie den Snap-Paketmanager verwenden. Abhängig von der Ubuntu-Distribution enthalten die Standard-APT-Repositories möglicherweise nicht die neueste Version der Software. In diesem Beispiel wird die Domänenüberprüfung mit Cloudflare als DNS-Anbieter verwendet. 1. Das folgende Beispiel zeigt Certbot, das als Root-Benutzer installiert und ausgeführt wird, während Devolutions Gateway als anderer Benutzer läuft. ```shell sudo snap install certbot --classic sudo snap set certbot trust-plugin-with-root=ok sudo snap install certbot-dns-cloudflare ``` 2. Wenn Sie Cloudflare verwenden, generieren Sie entweder ein benutzer- oder kontobezogenes API-Token mit der Vorlage **Edit zone DNS**. Sobald Sie das API-Token haben, erstellen Sie den enthaltenden Ordner und die entsprechende `.ini`-Datei, die das API-Token enthält. ```shell sudo install -d -m 0700 /root/.secrets sudo nano /root/.secrets/cloudflare.ini sudo chmod 0600 /root/.secrets/cloudflare.ini ``` 3. Fordern Sie ein Zertifikat für Ihre Devolutions Gateway-Domäne mit dem Cloudflare-DNS-Plugin an. Ersetzen Sie den unten stehenden Wert `gateway.mydomain.com` durch Ihre eigene Domäne. ```shell certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/.secrets/cloudflare.ini -d gateway.mydomain.com --cert-name gateway ``` 4. Ändern Sie Ihre Konfigurationsdatei `gateway.json`, um die folgenden Zeilen hinzuzufügen und das neu generierte Zertifikat zu verwenden, indem Sie das Devolutions Gateway PowerShell-Modul nutzen. Die folgenden Befehle ändern die Konfigurationsvariablen `TlsCertificateFile`, `TlsPrivateKeyFile` und `Listeners`. ```powershell Import-Module DevolutionsGateway Set-DGatewayConfig -TlsCertificateFile "/etc/letsencrypt/live/gateway/fullchain.pem" -TlsPrivateKeyFile "/etc/letsencrypt/live/gateway/privkey.pem" -Listeners @( @{ "InternalUrl" = "tcp://*:8181" "ExternalUrl" = "tcp://*:8181" } @{ "InternalUrl" = "https://*:7171" "ExternalUrl" = "https://*:7171" } ) ``` 5. Bevor Sie Devolutions Gateway neu starten können, um das neue Zertifikat zu verwenden, müssen Sie dem Benutzer, der Devolutions Gateway ausführt, das Lesen der Zertifikatsdateien erlauben. Hierbei wird davon ausgegangen, dass Ihr Benutzer **devolutions** heißt und das Zertifikat **gateway** heißt. Sie erteilen Traversierungsrechte für die Verzeichnisse und Leserechte für die Zertifikatsdateien selbst. ```shell sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/live sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/live/gateway sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/archive sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/archive/gateway sudo setfacl -m u:devolutions:r /etc/letsencrypt/live/gateway/fullchain.pem sudo setfacl -m u:devolutions:r /etc/letsencrypt/live/gateway/privkey.pem sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/fullchain*.pem sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/privkey*.pem # Reconfigure to add a deploy hook sudo certbot reconfigure --cert-name gateway --deploy-hook "sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/fullchain*.pem; sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/privkey*.pem; systemctl restart devolutions-gateway.service" ``` 6. Starten Sie Devolutions Gateway entweder mit dem Befehl `systemctl` oder dem Devolutions Gateway PowerShell-Modul neu. ```shell # Restart Gateway using systemctl systemctl restart devolutions-gateway.service ``` ```powershell # Restart Gateway using the Devolutions Gateway PowerShell module, assuming it is run in a pwsh shell. Import-Module DevolutionsGateway; Restart-DGateway ``` **LetsEncrypt-Zertifikat erneuern** Standardmäßig wird bei der Snap-Installationsmethode ein systemd-Timer verwendet (anstelle eines Cron-Jobs), der zweimal täglich ausgeführt wird (ein Zertifikat jedoch nur innerhalb von 30 Tagen vor seinem Ablauf erneuert). Um eine Erneuerung zu erzwingen, können Sie den folgenden Befehl verwenden. ``` sudo certbot renew # To perform a renewal dry run and force a restart of the service, you can use the following command: # sudo certbot renew --dry-run --run-deploy-hooks ``` #### Ein selbstsigniertes Zertifikat unter Ubuntu 22.04 LTS über OpenSSL generieren Mit dem OpenSSL-Dienstprogramm können Sie ein Zertifikat direkt über die Befehlszeile generieren. Das Zertifikat muss dann direkt in das Konfigurationsverzeichnis **/etc/devolutions-gateway** gelegt werden. ```powershell sudo openssl req -x509 -subj "/C=CA/ST=Quebec/L=Lavaltrie/O=Devolutions/CN=ubuntu-2204" -addext "subjectAltName = IP:10.10.0.20" -addext "extendedKeyUsage = serverAuth" -nodes -days 365 -newkey rsa:2048 -keyout /etc/devolutions-gateway/server.key -out /etc/devolutions-gateway/server.crt ``` Die Zertifikatsanfrage sieht für jede Konfiguration anders aus. Beachten Sie, dass das Zertifikat eine **Subject Alternative Name (SAN)**-Erweiterung mit entweder einem **DNS-Namen** oder einer **IP-Adresse** enthalten **muss**, und es sollte außerdem die **Extended Key Usage (EKU)**-Erweiterung mit dem Zweck **Server Authentication** (`serverAuth`) enthalten. Dies ist erforderlich, da moderne Betriebssysteme und Browser, einschließlich **Google Chrome** und **macOS,** Zertifikate ablehnen, bei denen ein SAN oder die entsprechende EKU fehlt, selbst wenn der Common Name (CN) gesetzt ist. Es ist möglich, diese Anforderung zu lockern, indem die Option `TlsVerifyStrict` bei Bedarf auf `false` gesetzt wird, dies wird jedoch nicht empfohlen.
AnpassungsoptionenErklärung
reqErstellt und verarbeitet Zertifikatsanfragen einschließlich selbstsignierter Zertifikate im PKCS#10-Format.
-x509Gibt ein selbstsigniertes Zertifikat aus.
-subj

Definiert den Zertifikatsbetreff über die Befehlszeile. Zwischen den Abschnitten darf es keine Leerzeichen geben

  • /C - Land als 2-stelliger Code wie „CA“ für Kanada oder „US“ für die Vereinigten Staaten.
  • /ST - Bundesland oder Provinz, wie Quebec oder Kalifornien.
  • /L - Ort, wie Lavaltrie oder Sacramento.
  • /O - Organisation, wie Devolutions oder Microsoft.
  • /CN - Common Name, hier ubuntu-2204 (wie über den Befehl hostname angezeigt).
-addext

Um einen Subject Alternate Name (SAN) hinzuzufügen, können Sie diesen Parameter verwenden, um entweder einen IP- oder DNS-Eintrag zu definieren.

  • "subjectAltName = IP:10.10.0.20"
  • "subjectAltName = DNS:ubuntu-2204"
-nodesVerschlüsselt den erstellten privaten Schlüssel nicht.
-daysDie Anzahl der Tage, für die das Zertifikat gültig ist.
-newkeyDefiniert den Algorithmus und die Bitgröße, hier wird rsa:2048 verwendet.
-keyoutDer Ort, an dem die Datei des privaten Schlüssels erstellt wird.
-outDer Ort, an dem die Datei des öffentlichen Schlüssels erstellt wird.
#### Dem selbstsignierten Zertifikat unter Ubuntu vertrauen Das TLS-Zertifikat hat zwei Zwecke: 1. Es sichert die Verwaltungs-API; 2. Es sichert jeden Client-zu-Gateway-Tunnel, in dem Gateway den Datenverkehr inspizieren oder filtern kann (Websites, Gateway-Tunnel, SCP/SFTP usw.).\ Bei opaken Protokollen wie RDP oder SSH leitet Devolutions Gateway einfach bereits verschlüsselte Bytes weiter, das Zertifikat ist jedoch weiterhin für Gateway-Health-Checks und zukünftige Funktionen erforderlich. Sobald das selbstsignierte Zertifikat erstellt wurde, muss dem Zertifikat innerhalb des Ubuntu-Systems vertraut werden. Um systemweites Vertrauen zu erreichen, verwenden Sie die folgenden Befehle: ```powershell cd /etc/devolutions-gateway sudo apt-get install -y ca-certificates sudo cp server.crt /usr/local/share/ca-certificates sudo update-ca-certificates ``` Die `ca-certificates` sind möglicherweise bereits installiert. Durch Ausführen des Befehls `update-ca-certificates` wird in `/etc/ssl/certs` ein Symlink zur kopierten Zertifikatsdatei in **/usr/local/share/ca-certificates** erstellt. {% hint style="warning" %} Wenn dies in Firefox durchgeführt wird, erscheinen mehrere Vertrauensfehler, da der Browser nicht den systemweiten Zertifikatspeicher verwendet. Die [Dokumentation](https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox) von Mozilla bietet hierfür einige Lösungen. {% endhint %} #### Dem selbstsignierten Zertifikat unter Windows vertrauen Nachdem das selbstsignierte Zertifikat erstellt wurde, muss ihm auf Devolutions Server vertraut werden. Die Dateien **server.crt** und **server.key** müssen auf das Windows-System übertragen werden; oder kopieren Sie den Inhalt und fügen Sie ihn in Dateien ein (d. h. **sudo cat server.crt** in Ubuntu und dies in eine Textdatei unter Windows kopieren). {% hint style="warning" %} Überspringen Sie diesen Abschnitt, wenn Devolutions Server nicht unter Windows läuft. {% endhint %} 1\. Kopieren Sie den öffentlichen Schlüssel nach Windows (im Beispiel ist **C:\Gateway** ein temporärer Ort):\ `sudo cat server.crt` 2. Kopieren Sie den Inhalt in eine **server.crt**-Datei. 3. Kopieren Sie den privaten Schlüssel nach Windows:\ `sudo cat server.key` 4. Kopieren Sie den Inhalt in eine **server.key**-Datei. 5. Erstellen Sie eine PFX-Datei mit dem Windows-Befehlszeilentool certutil. Damit dies funktioniert, muss die Schlüsseldatei denselben Namen wie die **crt**-Datei haben und sich nur in der Erweiterung unterscheiden:\ `certutil -mergepfx server.crt server.pfx` 6. Importieren Sie die PFX-Datei in den [Zertifikatspeicher „Vertrauenswürdige Stammzertifizierungsstellen“](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/trusted-root-certification-authorities-certificate-store). 1. Doppelklicken Sie auf die Datei **server.pfx**, um den Importassistenten zu starten, und wählen Sie ***Lokaler Computer***. 2. Klicken Sie auf ***Weiter*** und akzeptieren Sie die Aufforderung. 3. Klicken Sie auf ***Weiter***. 4. Geben Sie das Passwort ein, das Sie mit dem Befehl `certutil` eingegeben haben. * Optional: Wählen Sie ***Diesen Schlüssel als exportierbar markieren***. 5. Wählen Sie die Option ***Alle Zertifikate in folgendem Speicher speichern***. 6. Wählen Sie ***Vertrauenswürdige Stammzertifizierungsstellen*** mit der Schaltfläche ***Durchsuchen...*** aus. 7. Klicken Sie auf ***Weiter***. 8. Klicken Sie auf ***Fertig stellen***, um den Import abzuschließen. ### Ubuntu-Firewall-Ports öffnen Wenn das Linux-System UFW (Uncomplicated Firewall) zur Verwaltung der iptable-basierten Firewall verwendet, führen Sie die folgenden Befehle aus, um die erforderlichen Ports zu öffnen: ```powershell sudo ufw status sudo ufw allow 7171 sudo ufw allow 8181 sudo ufw status ``` ### Die Devolutions Gateway-Konfiguration ändern Der in der Datei **/etc/devolutions-gateway/gateway.json** enthaltenen Standardkonfiguration eines Gateways müssen die Zertifikatsanweisungen hinzugefügt werden (die `InternalUrl` muss HTTPS verwenden): ```powershell { "Id": "YOUR-UNIQUE-GUID", "ProvisionerPublicKeyFile": "provisioner.pem", "ProvisionerPrivateKeyFile": null, "Listeners": [ { "InternalUrl": "tcp://:8181", "ExternalUrl": "tcp://:8181" }, { "InternalUrl": "http://:7171", "ExternalUrl": "https://:7171" } ] } ``` Ändern Sie die obige Datei wie folgt, wobei davon ausgegangen wird, dass sich sowohl **server.crt** als auch **server.key** im selben Verzeichnis wie **gateway.json** befinden (die Verwendung des integrierten Dateieditors Nano wird empfohlen): ```powershell { "Id": "YOUR-UNIQUE-GUID", "ProvisionerPublicKeyFile": "provisioner.pem", "ProvisionerPrivateKeyFile": null, "TlsCertificateFile": "server.crt", "TlsPrivateKeyFile": "server.key", "Listeners": [ { "InternalUrl": "tcp://:8181", "ExternalUrl": "tcp://:8181" }, { "InternalUrl": "https://:7171", "ExternalUrl": "https://:7171" } ] } ``` #### Devolutions Gateway neu starten Starten Sie Devolutions Gateway mit der neuen Konfiguration neu. Dies kann mit dem Befehl `systemctl` erfolgen: ```powershell sudo systemctl restart devolutions-gateway.service sudo systemctl status devolutions-gateway.service ``` Alternativ können auch die PowerShell-Befehle `Stop-DGateway` und `Start-DGateway` verwendet werden. ### Devolutions Gateway mit Devolutions Server verbinden #### Den öffentlichen Schlüssel von Devolutions Server auf Devolutions Gateway Linux kopieren 1. Melden Sie sich an der Devolutions Server-Webkonsole an und navigieren Sie zu ***Administration***** – *****Devolutions Gateway***. 2. Klicken Sie auf die Schaltfläche ***Mehr*** und wählen Sie die Option ***Öffentlichen Schlüssel herunterladen***. 3. Kopieren Sie den Inhalt der heruntergeladenen Datei **gateway\_public\_key.pem** unter Windows. 4. Ersetzen Sie den Inhalt der Datei **/etc/devolutions-gateway/provisioner.pem** (das Dienstprogramm Nano wird empfohlen) durch den von Windows kopierten Inhalt. 5. Starten Sie Devolutions Gateway mit dem Befehl `sudo systemctl restart devolutions-gateway.service` neu. #### Devolutions Gateway in Devolutions Server konfigurieren Gehen Sie zur Devolutions Server-Weboberfläche, in der das neu konfigurierte Linux-Devolutions Gateway hinzugefügt wird. {% hint style="warning" %} Überspringen Sie diesen Abschnitt, wenn Sie Devolutions Gateway mit Devolutions Cloud installieren. {% endhint %} 1. Melden Sie sich an der Devolutions Server-Webkonsole an und navigieren Sie zu ***Administration*** – ***Devolutions Gateway***. 2. Klicken Sie auf die Schaltfläche ***Hinzufügen*** (***+***). 3. Wählen Sie ***Gateway***. 4. Geben Sie Folgendes ein (dies ändert sich je nach Konfiguration). 1. ***Name***: Linux Gateway 2. ***Devolutions Gateway-URL***: `https://10.10.0.20:7171` 3. ***TCP-Hostname***: `Ubuntu-2204` 5. Klicken Sie auf ***Speichern***.

Klicken Sie auf das Menü Mehr-Optionen für das Gateway und wählen Sie die Option Sperrliste veröffentlichen, wenn die Sperrliste nicht aktuell ist.

### Hosts in Ubuntu auflösen Das Linux-gehostete Devolutions Gateway-System muss in der Lage sein, die von Devolutions Server angeforderten Adressen aufzulösen. Die einfachste Methode zum Testen ist, die hosts-Datei zu ändern. Verbinden Sie sich mit dem folgenden System: * **Hostname**: `it-help-dc` * **Vollqualifizierter Domänenname (FQDN)**: `it-help-dc.ad.it-help.ninja` * **IP-Adresse**: `10.10.0.3` Öffnen Sie die hosts-Datei zum Bearbeiten mit `sudo nano /etc/hosts`, um den Host in Ubuntu hinzuzufügen. ### Eine webbasierte RDP-Sitzung öffnen Das Gateway kann sich nun mit Hosts verbinden. Da der Host `it-help-dc` für Ubuntu als auflösbar hinzugefügt wurde, kann er für eine Verbindung in einer webbasierten Sitzung verwendet werden. {% hint style="info" %} Webbasierte Sitzungen erfordern ein aktives, für den Eintrag konfiguriertes Gateway, und der startende Benutzer benötigt eine zugewiesene Remote Desktop Manager Team Edition-Lizenz oder eine Devolutions Launcher-Lizenz. Zusätzlich kann es, wenn Änderungen an den Lizenzzuweisungen vorgenommen wurden, erforderlich sein, sich ab- und wieder anzumelden, um die Option zum Starten der webbasierten Verbindung zu sehen. {% endhint %} 1. Klicken Sie in der Devolutions Server Web-Benutzeroberfläche auf ***Add***. Wählen Sie einen ***RDP***-Sitzungseintrag aus. 2. Klicken Sie auf ***Continue***. 3. Geben Sie einen ***Name*** und ***Host*** ein, der von der Linux-Installation von Devolutions Gateway auflösbar sein muss. 4. Klicken Sie auf ***Add***. 5. Geben Sie alle erforderlichen Anmeldeinformationen für die RDP-Sitzung ein oder verknüpfen Sie diese und klicken Sie auf ***Add***. 6. Wählen Sie im Tab ***VPN/Tunnel/Gateway*** Devolutions Gateway als VPN-Typ aus. 7. Setzen Sie die Option ***Connect*** auf ***Always connect***. 8. Wählen Sie das richtige Gateway aus. 9. Klicken Sie auf ***Add***. 10. Klicken Sie auf ***Open in web client***. ### Eine Remote Desktop Manager-RDP-Sitzung öffnen Wenn der Eintrag bereits in der Devolutions Server-Weboberfläche konfiguriert wurde, kann er aus Remote Desktop Manager gestartet werden, sofern eine Verbindung zur Devolutions Server-Datenquelle besteht. {% hint style="warning" %} Überspringen Sie diesen Abschnitt, wenn Sie Devolutions Gateway mit Devolutions Cloud installieren. {% endhint %} Beim Erstellen eines neuen Eintrags in Remote Desktop Manager ist der Vorgang ähnlich wie bei Devolutions Server. 1. Klicken Sie in Remote Desktop Manager auf ***New entry***. Wählen Sie einen RDP-Sitzungseintrag aus. 2. Klicken Sie auf ***Select***. 3. Geben Sie einen ***Name*** und ***Host*** ein, der von der Linux-Installation von Devolutions Gateway auflösbar sein muss. 4. Geben Sie alle erforderlichen Anmeldeinformationen für die RDP-Sitzung ein oder verknüpfen Sie diese. 5. Setzen Sie die Option ***Connect*** auf ***Always connect***. 6. Wählen Sie im Tab ***VPN/Tunnel/Gateway*** Devolutions Gateway als VPN-Typ aus. 7. Wechseln Sie zum Unter-Tab ***Settings (Devolutions Gateway)***. 8. Wählen Sie das gewünschte Devolutions Gateway aus. 9. Klicken Sie auf ***Add***. 10. Klicken Sie auf die Schaltfläche ***Open session***.

Wenn Sie den Mauszeiger über die Titelleiste bewegen, erscheint ein Tooltip, der anzeigt, dass die RDP-Verbindung über Devolutions Gateway hergestellt wurde.

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/gateway/de/getting-started/devolutions-gateway-configuration-on-linux.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.