plugin_name: python.d.plugin
modules:
  - meta:
      plugin_name: python.d.plugin
      module_name: samba
      monitored_instance:
        name: Samba
        link: https://www.samba.org/samba/
        categories:
          - data-collection.storage-mount-points-and-filesystems
        icon_filename: "samba.svg"
      related_resources:
        integrations:
          list: []
      info_provided_to_referring_integrations:
        description: ""
      keywords:
        - samba
        - file sharing
      most_popular: false
    overview:
      data_collection:
        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: false
      additional_permissions:
        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: "After all the permissions are satisfied, the `smbstatus -P` binary is executed."
        limits:
          description: ""
        performance_impact:
          description: ""
    setup:
      prerequisites:
        list:
          - title: Enable the samba collector
            description: |
              The `samba` collector is disabled by default. To enable it, use `edit-config` from the Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`, to edit the `python.d.conf` file.

              ```bash
              cd /etc/netdata   # Replace this path with your Netdata config directory, if different
              sudo ./edit-config python.d.conf
              ```
              Change the value of the `samba` setting to `yes`. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for your system.
          - 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: python.d/samba.conf
        options:
          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: "Config options"
            enabled: true
          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: "Config"
          list:
            - name: Basic
              description: A basic example configuration.
              config: |
                my_job_name:
                  name: my_name
                  update_every: 1
    troubleshooting:
      problems:
        list: []
    alerts: []
    metrics:
      folding:
        title: Metrics
        enabled: false
      description: ""
      availability: []
      scopes:
        - 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