Console Documentation Updates (#470)

* Rename files to sub folder * WIP Improve enrollment docs * Add more enrollment ideas * Add promo at end of each installation guide and stuff * Add force for windows and nix * Fix overwrite flag * Minor wod
crowdsecurity · Oct 19, 2023 · 384a370 · 384a370
1 parent 98d6bbb
commit 384a370
Show file tree

Hide file tree

Showing 10 changed files with 158 additions and 21 deletions.
diff --git a/...docs/docs/console_management/decisions.md → crowdsec-docs/docs/console/decisions.md b/...docs/docs/console_management/decisions.md → crowdsec-docs/docs/console/decisions.md
diff --git a/...sec-docs/docs/console_management/intro.md → ...dsec-docs/docs/console/decisions_intro.md b/...sec-docs/docs/console_management/intro.md → ...dsec-docs/docs/console/decisions_intro.md
@@ -1,5 +1,5 @@
 ---
-id: intro
+id: decisions_intro
 title: Introduction
 sidebar_position: 1
 ---

diff --git a/crowdsec-docs/docs/console/enrollment.mdx b/crowdsec-docs/docs/console/enrollment.mdx
@@ -0,0 +1,109 @@
+---
+id: enrollment
+title: Enrollment
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+:::info
+$ID will be used as the placeholder for your enrollment ID, you can find this within the [console](https://app.crowdsec.net/).
+:::
+
+## Standalone
+
+You can enroll a [Security Engine](/getting_started/getting_started.md) into the console to get a overview of your alerts. This process is handled by the following `cscli` command:
+
+<Tabs
+  defaultValue="nix"
+  groupId="console-operating-systems"
+  values={[
+    {label: 'Linux/Freebsd', value: 'nix'},
+    {label: 'Windows', value: 'windows'},
+  ]}>
+  <TabItem value="nix">
+    <CodeBlock className="language-bash">sudo cscli console enroll $ID</CodeBlock>
+  </TabItem>
+  <TabItem value="windows">
+    <CodeBlock className="language-bash">cscli.exe console enroll $ID</CodeBlock>
+  </TabItem>
+</Tabs>
+
+## Docker / Podman
+
+:::info
+Docker commands are interchangeable with podman.
+:::
+
+If you are using docker, you can enroll the Security Engine by passing the enrollment ID as an environment variable:
+
+```bash
+docker run -e ENROLL_KEY=$ID crowdsecurity/crowdsec
+```
+
+If you already have a deployment running this can also be enrolled by using the `cscli` command:
+
+```bash
+docker exec -it <CONTAINER_ID> cscli console enroll $ID
+```
+
+If you are using automatic deployments, then you can automate the enrollment process depending on the system:
+
+## K8s / Helm
+
+K8's and helm use our standard container image so can also use the enrollment ID as an environment variable:
+
+```yaml
+lapi:
+  env:
+    - name: ENROLL_KEY
+      value: $ID
+```
+
+:::info
+Note here we are placing it within the LAPI environment **NOT** the agent as the agent is not responsible for the enrollment process.
+:::
+
+## Chef, Puppet, Ansible
+
+If you are using a configuration management tool, you can use the `cscli` command to enroll the Security Engine:
+
+```bash
+sudo cscli console enroll $ID
+```
+
+---
+
+# Troubleshooting
+
+## Where can I find my enrollment key?
+
+You can find your enrollment key within the [console](https://app.crowdsec.net/).
+
+Once you have authenticated, you can find the key within the `Add Security Engine` button on the [Security Engines page](https://app.crowdsec.net/security-engines).
+
+## My security engine is failing to connect to the console?
+
+The Security Engine and `cscli` must have internet access, this can be through a proxy or directly. If you are using a proxy, you can configure it using the GOLANG `HTTP_PROXY` and `HTTPS_PROXY` environment variables
+
+## My security engine has already been enrolled on another account, can I transfer it?
+
+Yes, you can transfer the security engine within the console interface to another organization.
+
+If for whatever reason you cannot access the old account you can force the new enrollment by running the `cscli` command with the overwrite flag:
+
+<Tabs
+  defaultValue="nix"
+  groupId="console-operating-systems"
+  values={[
+    {label: 'Linux/Freebsd', value: 'nix'},
+    {label: 'Windows', value: 'windows'},
+  ]}>
+  <TabItem value="nix">
+    <CodeBlock className="language-bash">sudo cscli console enroll $ID --overwrite</CodeBlock>
+  </TabItem>
+  <TabItem value="windows">
+    <CodeBlock className="language-bash">cscli.exe console enroll $ID --overwrite</CodeBlock>
+  </TabItem>
+</Tabs>
diff --git a/crowdsec-docs/docs/console.md → crowdsec-docs/docs/console/intro.md b/crowdsec-docs/docs/console.md → crowdsec-docs/docs/console/intro.md
@@ -1,5 +1,5 @@
 ---
-id: console
+id: intro
 title: Console
 sidebar_position: 10
 ---
@@ -15,17 +15,10 @@ The [console](https://app.crowdsec.net) is a web interface hosted by crowdsec th
 
 Once your [registration done](https://app.crowdsec.net/signup), follow the tour !
 
-
-You will be able to register any instance directly from `cscli` :
-
-```bash
-sudo cscli console enroll <id> 
-```
+Then [enroll your instance](/console/enrollment.mdx) to the console.
 
 And see what's going in the console :
 
 ![instance-overview](/img/console-instance-overview.png)
 
-
-
 ![stats-overview](/img/console-stats-overview.png)
diff --git a/crowdsec-docs/docs/getting_started/getting_started.md b/crowdsec-docs/docs/getting_started/getting_started.md
@@ -53,3 +53,9 @@ Once you have installed the Security Engine, you can install a Remediation Compo
 Depending on your network / OS setup, you will need to install a different Remediation Component.
 
 If you are unsure which to install, please see our [Remediation Components](/bouncers/intro.md) section OR join our [discord](https://discord.gg/crowdsec) and ask our community.
+
+## Enrolling your instance
+
+Next step is to enroll your instance to the CrowdSec console. This will allow you to view your instance in the console, and enhance your security by using our third party lists.
+
+See the [console section](/console/intro.md) for more information.
diff --git a/crowdsec-docs/docs/getting_started/getting_started_on_windows.md b/crowdsec-docs/docs/getting_started/getting_started_on_windows.md
@@ -182,3 +182,9 @@ To do so, open an administrator powershell or DOS prompt and run `cscli.exe boun
 Add this key in the Remediation Component configuration file located in `C:\Program Files\CrowdSec\bouncers\cs-windows-firewall-bouncer\cs-windows-firewall-bouncer.yaml`.
 
 When done, you will need to enable the `cs-windows-firewall-bouncer` service and start it.
+
+## Enrolling your instance
+
+Next step is to enroll your instance to the CrowdSec console. This will allow you to view your instance in the console, and enhance your security by using our third party lists.
+
+See the [console section](/console/intro.md) for more information.
diff --git a/crowdsec-docs/docs/getting_started/install.mdx b/crowdsec-docs/docs/getting_started/install.mdx
@@ -170,3 +170,8 @@ do:
 5. install the arm gcc cross compiler (On debian the package is gcc-arm-linux-gnueabihf)
 6. Compile CrowdSec using the usual `make` command
 
+## Enrolling your instance
+
+Next step is to enroll your instance to the CrowdSec console. This will allow you to view your instance in the console, and enhance your security by using our third party lists.
+
+See the [console section](/console/intro.md) for more information.
diff --git a/crowdsec-docs/docs/getting_started/install_freebsd.md b/crowdsec-docs/docs/getting_started/install_freebsd.md
@@ -137,3 +137,9 @@ Start `hostid` and `hostid_save`:
 ```
 
 Then start again the CrowdSec' service  `service crowdsec start`.
+
+## Enrolling your instance
+
+Next step is to enroll your instance to the CrowdSec console. This will allow you to view your instance in the console, and enhance your security by using our third party lists.
+
+See the [console section](/console/intro.md) for more information.
diff --git a/crowdsec-docs/docs/getting_started/install_opnsense.md b/crowdsec-docs/docs/getting_started/install_opnsense.md
@@ -122,3 +122,8 @@ For more information on the topic:
 
  - [Improve The CrowdSec Multi-Server Installation With HTTPS Between Agents](https://www.linuxjournal.com/content/improve-crowdsec-multi-server-installation-https-between-agents) (Linux Journal)
 
+## Enrolling your instance
+
+Next step is to enroll your instance to the CrowdSec console. This will allow you to view your instance in the console, and enhance your security by using our third party lists.
+
+See the [console section](/console/intro.md) for more information.
diff --git a/crowdsec-docs/sidebars.js b/crowdsec-docs/sidebars.js
@@ -393,15 +393,7 @@
                 },
             ],
         },
-        {
-            type: "category",
-            label: "Console Management",
-            link: {
-                type: "doc",
-                id: "console_management/intro",
-            },
-            items: ["console_management/decisions"],
-        },
+
         {
             type: "category",
             label: "Expr",
@@ -437,9 +429,24 @@
             ],
         },
         {
-            type: "doc",
+            type: "category",
             label: "Console",
-            id: "console",
+            link: {
+                type: "doc",
+                id: "console/intro",
+            },
+            items: [
+                'console/enrollment',
+                {
+                    type: "category",
+                    label: "Decision Management",
+                    link: {
+                        type: "doc",
+                        id: "console/decisions_intro",
+                    },
+                    items: ["console/decisions"],
+                },
+            ]
         },
         {
             type: "doc",