Add Samba collector yaml (#15507)

1 files changed, 152 insertions, 81 deletions

diff --git a/collectors/python.d.plugin/samba/metadata.yaml b/collectors/python.d.plugin/samba/metadata.yaml
index ab7b25e699..c53d62043b 100644
--- a/collectors/python.d.plugin/samba/metadata.yaml
+++ b/collectors/python.d.plugin/samba/metadata.yaml
@@ -3,52 +3,123 @@ meta:
   module_name: samba
   monitored_instance:
     name: Samba
-    link: ''
+    link: https://www.samba.org/samba/
     categories:
-    - data-collection.storage-mount-points-and-filesystems
-    icon_filename: 'samba.jpg'
+      - data-collection.storage-mount-points-and-filesystems
+    icon_filename: "samba.jpg"
   related_resources:
     integrations:
       list: []
   info_provided_to_referring_integrations:
-    description: ''
-  keywords: []
+    description: ""
+  keywords:
+    - samba
+    - file sharing
   most_popular: false
 overview:
   data_collection:
-    metrics_description: 'Monitor Samba performance for optimal network file sharing operations. Netdata provides real-time insights and alerts for efficient file sharing.'
-    method_description: ''
+    metrics_description: "This collector monitors the performance metrics of Samba file sharing."
+    method_description: |
+      It is using the `smbstatus` command-line tool.
+
+      Executed commands:
+
+      - `sudo -n smbstatus -P`
   supported_platforms:
     include: []
     exclude: []
-  multi_instance: true
+  multi_instance: false
   additional_permissions:
-    description: ''
+    description: |
+      `smbstatus` is used, which can only be executed by `root`. It uses `sudo` and assumes that it is configured such that the `netdata` user can execute `smbstatus` as root without a password.
   default_behavior:
     auto_detection:
-      description: ''
+      description: "After all the permissions are satisfied, the `smbstatus -P` binary is executed."
     limits:
-      description: ''
+      description: ""
     performance_impact:
-      description: ''
+      description: ""
 setup:
   prerequisites:
-    list: []
+    list:
+      - title: Permissions and programs
+        description: |
+          To run the collector you need:
+
+          - `smbstatus` program
+          - `sudo` program
+          - `smbd` must be compiled with profiling enabled
+          - `smbd` must be started either with the `-P 1` option or inside `smb.conf` using `smbd profiling level`
+
+          The module uses `smbstatus`, which can only be executed by `root`. It uses `sudo` and assumes that it is configured such that the `netdata` user can execute `smbstatus` as root without a password.
+
+          - add to your `/etc/sudoers` file:
+
+            `which smbstatus` shows the full path to the binary.
+
+            ```bash
+            netdata ALL=(root)       NOPASSWD: /path/to/smbstatus
+            ```
+
+          - Reset Netdata's systemd unit [CapabilityBoundingSet](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Capabilities) (Linux distributions with systemd)
+
+            The default CapabilityBoundingSet doesn't allow using `sudo`, and is quite strict in general. Resetting is not optimal, but a next-best solution given the inability to execute `smbstatus` using `sudo`.
+
+
+            As the `root` user, do the following:
+
+            ```cmd
+            mkdir /etc/systemd/system/netdata.service.d
+            echo -e '[Service]\nCapabilityBoundingSet=~' | tee /etc/systemd/system/netdata.service.d/unset-capability-bounding-set.conf
+            systemctl daemon-reload
+            systemctl restart netdata.service
+            ```
   configuration:
     file:
-      name: ''
-      description: ''
+      name: python.d/samba.conf
     options:
-      description: ''
+      description: |
+        There are 2 sections:
+
+        * Global variables
+        * One or more JOBS that can define multiple different instances to monitor.
+
+        The following options can be defined globally: priority, penalty, autodetection_retry, update_every, but can also be defined per JOB to override the global values.
+
+        Additionally, the following collapsed table contains all the options that can be configured inside a JOB definition.
+
+        Every configuration JOB starts with a `job_name` value which will appear in the dashboard, unless a `name` parameter is specified.
       folding:
-        title: ''
+        title: "Config options"
         enabled: true
-      list: []
+      list:
+        - name: update_every
+          description: Sets the default data collection frequency.
+          default_value: 5
+          required: false
+        - name: priority
+          description: Controls the order of charts at the netdata dashboard.
+          default_value: 60000
+          required: false
+        - name: autodetection_retry
+          description: Sets the job re-check interval in seconds.
+          default_value: 0
+          required: false
+        - name: penalty
+          description: Indicates whether to apply penalty to update_every in case of failures.
+          default_value: yes
+          required: false
     examples:
       folding:
         enabled: true
-        title: ''
-      list: []
+        title: "Config"
+      list:
+        - name: Basic
+          description: A basic example configuration.
+          config: |
+            my_job_name:
+              name: my_name
+              update_every: 1
 troubleshooting:
   problems:
     list: []
@@ -60,64 +131,64 @@ metrics:
   description: ""
   availability: []
   scopes:
-  - name: global
-    description: ""
-    labels: []
-    metrics:
-    - name: syscall.rw
-      description: R/Ws
-      unit: "KiB/s"
-      chart_type: area
-      dimensions:
-      - name: sendfile
-      - name: recvfile
-    - name: smb2.rw
-      description: R/Ws
-      unit: "KiB/s"
-      chart_type: area
-      dimensions:
-      - name: readout
-      - name: writein
-      - name: readin
-      - name: writeout
-    - name: smb2.create_close
-      description: Create/Close
-      unit: "operations/s"
-      chart_type: line
-      dimensions:
-      - name: create
-      - name: close
-    - name: smb2.get_set_info
-      description: Info
-      unit: "operations/s"
-      chart_type: line
-      dimensions:
-      - name: getinfo
-      - name: setinfo
-    - name: smb2.find
-      description: Find
-      unit: "operations/s"
-      chart_type: line
-      dimensions:
-      - name: find
-    - name: smb2.notify
-      description: Notify
-      unit: "operations/s"
-      chart_type: line
-      dimensions:
-      - name: notify
-    - name: smb2.sm_counters
-      description: Lesser Ops
-      unit: "count"
-      chart_type: stacked
-      dimensions:
-      - name: tcon
-      - name: negprot
-      - name: tdis
-      - name: cancel
-      - name: logoff
-      - name: flush
-      - name: lock
-      - name: keepalive
-      - name: break
-      - name: sessetup
+    - name: global
+      description: "These metrics refer to the entire monitored application."
+      labels: []
+      metrics:
+        - name: syscall.rw
+          description: R/Ws
+          unit: "KiB/s"
+          chart_type: area
+          dimensions:
+            - name: sendfile
+            - name: recvfile
+        - name: smb2.rw
+          description: R/Ws
+          unit: "KiB/s"
+          chart_type: area
+          dimensions:
+            - name: readout
+            - name: writein
+            - name: readin
+            - name: writeout
+        - name: smb2.create_close
+          description: Create/Close
+          unit: "operations/s"
+          chart_type: line
+          dimensions:
+            - name: create
+            - name: close
+        - name: smb2.get_set_info
+          description: Info
+          unit: "operations/s"
+          chart_type: line
+          dimensions:
+            - name: getinfo
+            - name: setinfo
+        - name: smb2.find
+          description: Find
+          unit: "operations/s"
+          chart_type: line
+          dimensions:
+            - name: find
+        - name: smb2.notify
+          description: Notify
+          unit: "operations/s"
+          chart_type: line
+          dimensions:
+            - name: notify
+        - name: smb2.sm_counters
+          description: Lesser Ops
+          unit: "count"
+          chart_type: stacked
+          dimensions:
+            - name: tcon
+            - name: negprot
+            - name: tdis
+            - name: cancel
+            - name: logoff
+            - name: flush
+            - name: lock
+            - name: keepalive
+            - name: break
+            - name: sessetup