From 891fc4d8cc31b1e1c1de64f29ddf81006ec4c7fd Mon Sep 17 00:00:00 2001
From: Jule Anger <janger@samba.org>
Date: Mon, 15 Aug 2022 15:27:55 +0200
Subject: [PATCH] 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>

(cherry picked from commit ddbf1b29eee140b3112eb238852bfdc8285eb04f)
---
 docs-xml/manpages/smbstatus.1.xml | 264 ++++++++++++++++++++++++++++++
 1 file changed, 264 insertions(+)

diff --git a/docs-xml/manpages/smbstatus.1.xml b/docs-xml/manpages/smbstatus.1.xml
index e0945761b28..63ae4641bf1 100644
--- 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>
-- 
2.25.1