manpages: add smbstatus option --json with sample output

BUG: https://bugzilla.samba.org/show_bug.cgi?id=15147

Signed-off-by: Jule Anger <janger@samba.org>
Reviewed-by: Ralph Boehme <slow@samba.org>
Autobuild-User(master): Jule Anger <janger@samba.org>
Autobuild-Date(master): Tue Aug 16 15:04:54 UTC 2022 on sn-devel-184

diff --git a/docs-xml/manpages/smbstatus.1.xml b/docs-xml/manpages/smbstatus.1.xml
index e0945761b28f5687bfd9a748d1e5064d794e2f7f..63ae4641bf16595e39ab4e470f8e41efbfa0844b 100644 (file)
--- a/docs-xml/manpages/smbstatus.1.xml
+++ b/docs-xml/manpages/smbstatus.1.xml
@@ -31,6 +31,7 @@
                <arg choice="opt">-B|--byterange</arg>
                <arg choice="opt">-n|--numeric</arg>
                <arg choice="opt">-f|--fast</arg>
+               <arg choice="opt">-j|--json</arg>
                <arg choice="opt">--resolve-uids</arg>
                <arg choice="opt">-?|--help</arg>
                <arg choice="opt">--usage</arg>
@@ -136,6 +137,269 @@
                </listitem>
                </varlistentry>
 
+               <varlistentry>
+               <term>-j|--json</term>
+               <listitem><para>Output more detailed information in JSON format instead
+                               of human readable.
+                               The output has the following format:
+                               <programlisting>
+{
+  "timestamp": "2022-04-15T18:25:15.364891+0200",
+  "version": "4.17.0pre1-GIT-a0f12b9c80b",
+  "smb_conf": "/opt/samba/etc/smb.conf",
+  "sessions": {
+    "3639217376": {
+      "session_id": "3639217376",
+      "server_id": {
+        "pid": "69650",
+        "task_id": "0",
+        "vnn": "4294967295",
+        "unique_id": "10756714984493602300"
+      },
+      "uid": 1000,
+      "gid": 1000,
+      "username": "johndoe",
+      "groupname": "johndoe",
+      "remote_machine": "127.0.0.1",
+      "hostname": "ipv4:127.0.0.1:59944",
+      "session_dialect": "SMB3_11",
+      "encryption": {
+        "cipher": "",
+        "degree": "none"
+      },
+      "signing": {
+        "cipher": "AES-128-GMAC",
+        "degree": "partial"
+      }
+    }
+  },
+  "tcons": {
+    "3813255619": {
+      "service": "sharename",
+      "server_id": {
+        "pid": "69650",
+        "task_id": "0",
+        "vnn": "4294967295",
+        "unique_id": "10756714984493602300"
+      },
+      "tcon_id": "3813255619",
+      "session_id": "3639217376",
+      "machine": "127.0.0.1",
+      "connected_at": "2022-04-15T17:30:37+0200",
+      "encryption": {
+        "cipher": "AES-128-GMAC",
+        "degree": "full"
+      },
+      "signing": {
+        "cipher": "",
+        "degree": "none"
+      }
+    }
+  },
+  "open_files": {
+    "/home/johndoe/testfolder/sample": {
+      "service_path": "/home/johndoe/testfolder",
+      "filename": "sample",
+      "fileid": {
+        "devid": 59,
+        "inode": 11404245,
+        "extid": 0
+      },
+      "num_pending_deletes": 0,
+      "opens": {
+        "56839/2": {
+          "server_id": {
+            "pid": "69650",
+            "task_id": "0",
+            "vnn": "4294967295",
+            "unique_id": "10756714984493602300"
+          },
+          "uid": 1000,
+          "share_file_id": 2,
+          "sharemode": {
+            "hex": "0x00000003",
+            "NONE": false,
+            "READ": true,
+            "WRITE": true,
+            "DELETE": false,
+            "text": "RW"
+          },
+          "access_mask": {
+            "hex": "0x00000003",
+            "READ_DATA": true,
+            "WRITE_DATA": true,
+            "APPEND_DATA": false,
+            "READ_EA": false,
+            "WRITE_EA": false,
+            "EXECUTE": false,
+            "READ_ATTRIBUTES": false,
+            "WRITE_ATTRIBUTES": false,
+            "DELETE_CHILD": false,
+            "DELETE": false,
+            "READ_CONTROL": false,
+            "WRITE_DAC": false,
+            "SYNCHRONIZE": false,
+            "ACCESS_SYSTEM_SECURITY": false,
+            "text": "RW"
+          },
+          "caching": {
+            "READ": false,
+            "WRITE": false,
+            "HANDLE": false,
+            "hex": "0x00000000",
+            "text": ""
+          },
+          "oplock": {},
+          "lease": {},
+          "opened_at": "2022-04-15T17:30:38+0200"
+        }
+      }
+    }
+  }
+}
+                               </programlisting> </para>
+
+                       <para>If oplocks are used:
+                               <programlisting>
+          "oplock": {
+            "EXCLUSIVE": false,
+            "BATCH": false,
+            "LEVEL_II": true,
+            "LEASE": false,
+            "text": "LEVEL_II"
+          }
+                               </programlisting> </para>
+
+                       <para>If leases are used:
+
+                               <programlisting>
+          "lease": {
+            "lease_key": "29316055-f55c-de10-c813-af7bf5a430bb",
+            "hex": "0x00000005",
+            "READ": true,
+            "WRITE": true,
+            "HANDLE": false,
+            "text": "RW"
+          }
+                       </programlisting> </para>
+
+                       <para>With byte-range locks (-B, --byterange):
+                               <programlisting>
+  "byte_range_locks": {
+    "/home/johndoe/testfolder/sample": {
+      "fileid": {
+        "devid": 59,
+        "inode": 11404245,
+        "extid": 0
+      },
+      "file_name": "sample",
+      "share_path": "/home/johndoe/testfolder",
+      "locks": [
+        {
+          "server_id": {
+            "pid": "69650",
+            "task_id": "0",
+            "vnn": "4294967295",
+            "unique_id": "10756714984493602300"
+          },
+          "type": "R",
+          "flavour": "Posix",
+          "start": 0,
+          "size": 16
+        }
+      ]
+    }
+                       </programlisting> </para>
+
+                       <para> With notifies (-N, --notify):
+                               <programlisting>
+  "notify": {
+    "77247": {
+      "server_id": {
+        "pid": "69650",
+        "task_id": "0",
+        "vnn": "4294967295",
+        "unique_id": "10756714984493602300"
+      },
+      "path": "/home/johndoe/testfolder/testdir",
+      "filter": 4095,
+      "subdir_filter": 4095,
+      "creation_time": "1970-01-01T01:00:14.326582+01:00"
+    }
+  }
+                       </programlisting> </para>
+
+                       <para> For profiling (-P, --profile):
+                               <programlisting>
+{
+  "timestamp": "2022-04-15T18:40:43.112216+0200",
+  "version": "4.17.0pre1-GIT-a0f12b9c80b",
+  "smb_conf": "/opt/samba/etc/smb.conf",
+  "SMBD loop": {
+    "connect": {
+      "count": 2
+    },
+    "disconnect": {
+      "count": 1
+    },
+    ...
+  },
+  "System Calls": {
+    "syscall_opendir": {
+      "count": 0,
+      "time": 0
+    },
+    ...
+  },
+  "ACL Calls": {
+    "get_nt_acl": {
+      "count": 0,
+      "time": 0
+    },
+    ...
+  },
+  "Stat Cache": {
+    "statcache_lookups": {
+      "count": 2
+    },
+    ...
+  },
+  "SMB Calls": {
+    "SMBmkdir": {
+      "count": 0,
+      "time": 0
+    },
+    ...
+  },
+  "Trans2 Calls": {
+    "Trans2_open": {
+      "count": 0,
+      "time": 0
+    },
+    ...
+  },
+  "NT Transact Calls": {
+    "NT_transact_create": {
+      "count": 0,
+      "time": 0
+    },
+    ...
+  },
+  "SMB2 Calls": {
+    "smb2_negprot": {
+      "count": 2,
+      "time": 3060,
+      "idle": 0,
+      "inbytes": 452,
+      "outbytes": 568
+    },
+    ...
+  }
+}
+                       </programlisting> </para>
+               </listitem>
+               </varlistentry>
+
                &popt.autohelp;
                &cmdline.common.samba.client;
        </variablelist>