From c86a78bef7b1b7ada7b9cd025e3e8508a5fde6ad Mon Sep 17 00:00:00 2001
From: Armin Novak <armin.novak@thincast.com>
Date: Wed, 2 Oct 2024 16:48:48 +0200
Subject: [PATCH] [man] add manpage for global configuration

---
 client/SDL/SDL2/man/CMakeLists.txt            | 11 +--
 client/SDL/SDL2/man/sdl2-freerdp.1.xml.in     |  3 +
 client/SDL/SDL3/man/CMakeLists.txt            | 11 +--
 client/SDL/SDL3/man/sdl3-freerdp.1.xml.in     |  3 +
 client/X11/man/CMakeLists.txt                 | 11 +--
 client/X11/man/xfreerdp.1.xml.in              |  3 +
 .../common/man/freerdp-global-config.1.xml.in | 76 +++++++++++++++++++
 7 files changed, 103 insertions(+), 15 deletions(-)
 create mode 100644 client/common/man/freerdp-global-config.1.xml.in

diff --git a/client/SDL/SDL2/man/CMakeLists.txt b/client/SDL/SDL2/man/CMakeLists.txt
index 522448893..d4087f361 100644
--- a/client/SDL/SDL2/man/CMakeLists.txt
+++ b/client/SDL/SDL2/man/CMakeLists.txt
@@ -1,8 +1,9 @@
 set(DEPS
-		../../common/man/sdl-freerdp-channels.1.xml
-		../../common/man/sdl-freerdp-config.1.xml
-		../../common/man/sdl-freerdp-examples.1.xml
-		../../common/man/sdl-freerdp-envvar.1.xml
-    )
+	../../common/man/sdl-freerdp-channels.1.xml
+	../../common/man/sdl-freerdp-config.1.xml
+	../../common/man/sdl-freerdp-examples.1.xml
+	../../common/man/sdl-freerdp-envvar.1.xml
+	../../../common/man/freerdp-global-config.1.xml
+)
 
 generate_and_install_freerdp_man_from_xml(${MODULE_NAME} "1" "${DEPS}")
diff --git a/client/SDL/SDL2/man/sdl2-freerdp.1.xml.in b/client/SDL/SDL2/man/sdl2-freerdp.1.xml.in
index ba5b6cbf8..2573855d4 100644
--- a/client/SDL/SDL2/man/sdl2-freerdp.1.xml.in
+++ b/client/SDL/SDL2/man/sdl2-freerdp.1.xml.in
@@ -5,6 +5,7 @@ PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 	<!ENTITY syntax SYSTEM "freerdp-argument.1.xml">
 	<!ENTITY config SYSTEM "sdl-freerdp-config.1.xml">
 	<!ENTITY envvar SYSTEM "sdl-freerdp-envvar.1.xml">
+	<!ENTITY configuration SYSTEM "freerdp-global-config.1.xml">
 	<!ENTITY examples SYSTEM "sdl-freerdp-examples.1.xml">
 	]
 >
@@ -53,6 +54,8 @@ PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 		
 	&envvar;
 
+	&configuration;
+
 	&examples;
 
 	<refsect1>
diff --git a/client/SDL/SDL3/man/CMakeLists.txt b/client/SDL/SDL3/man/CMakeLists.txt
index 522448893..d4087f361 100644
--- a/client/SDL/SDL3/man/CMakeLists.txt
+++ b/client/SDL/SDL3/man/CMakeLists.txt
@@ -1,8 +1,9 @@
 set(DEPS
-		../../common/man/sdl-freerdp-channels.1.xml
-		../../common/man/sdl-freerdp-config.1.xml
-		../../common/man/sdl-freerdp-examples.1.xml
-		../../common/man/sdl-freerdp-envvar.1.xml
-    )
+	../../common/man/sdl-freerdp-channels.1.xml
+	../../common/man/sdl-freerdp-config.1.xml
+	../../common/man/sdl-freerdp-examples.1.xml
+	../../common/man/sdl-freerdp-envvar.1.xml
+	../../../common/man/freerdp-global-config.1.xml
+)
 
 generate_and_install_freerdp_man_from_xml(${MODULE_NAME} "1" "${DEPS}")
diff --git a/client/SDL/SDL3/man/sdl3-freerdp.1.xml.in b/client/SDL/SDL3/man/sdl3-freerdp.1.xml.in
index ba5b6cbf8..2573855d4 100644
--- a/client/SDL/SDL3/man/sdl3-freerdp.1.xml.in
+++ b/client/SDL/SDL3/man/sdl3-freerdp.1.xml.in
@@ -5,6 +5,7 @@ PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 	<!ENTITY syntax SYSTEM "freerdp-argument.1.xml">
 	<!ENTITY config SYSTEM "sdl-freerdp-config.1.xml">
 	<!ENTITY envvar SYSTEM "sdl-freerdp-envvar.1.xml">
+	<!ENTITY configuration SYSTEM "freerdp-global-config.1.xml">
 	<!ENTITY examples SYSTEM "sdl-freerdp-examples.1.xml">
 	]
 >
@@ -53,6 +54,8 @@ PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 		
 	&envvar;
 
+	&configuration;
+
 	&examples;
 
 	<refsect1>
diff --git a/client/X11/man/CMakeLists.txt b/client/X11/man/CMakeLists.txt
index 01d66464f..21c8a76a4 100644
--- a/client/X11/man/CMakeLists.txt
+++ b/client/X11/man/CMakeLists.txt
@@ -1,8 +1,9 @@
 set(DEPS
-        xfreerdp-channels.1.xml
-        xfreerdp-examples.1.xml
-        xfreerdp-shortcuts.1.xml
-        xfreerdp-envvar.1.xml
-    )
+	xfreerdp-channels.1.xml
+	xfreerdp-examples.1.xml
+	xfreerdp-shortcuts.1.xml
+	xfreerdp-envvar.1.xml
+	../../common/man/freerdp-global-config.1.xml
+)
 
 generate_and_install_freerdp_man_from_xml(${MODULE_NAME} "1" "${DEPS}")
diff --git a/client/X11/man/xfreerdp.1.xml.in b/client/X11/man/xfreerdp.1.xml.in
index 7e7c782f7..40f342e08 100644
--- a/client/X11/man/xfreerdp.1.xml.in
+++ b/client/X11/man/xfreerdp.1.xml.in
@@ -6,6 +6,7 @@ PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 	<!ENTITY shortcuts SYSTEM "xfreerdp-shortcuts.1.xml">
 	<!ENTITY channels SYSTEM "xfreerdp-channels.1.xml">
 	<!ENTITY envvar SYSTEM "xfreerdp-envvar.1.xml">
+	<!ENTITY configuration SYSTEM "freerdp-global-config.1.xml">
 	<!ENTITY examples SYSTEM "xfreerdp-examples.1.xml">
 	]
 >
@@ -56,6 +57,8 @@ PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 
 	&envvar;
 
+	&configuration;
+
 	&examples;
 
 	<refsect1>
diff --git a/client/common/man/freerdp-global-config.1.xml.in b/client/common/man/freerdp-global-config.1.xml.in
new file mode 100644
index 000000000..21de1880b
--- /dev/null
+++ b/client/common/man/freerdp-global-config.1.xml.in
@@ -0,0 +1,76 @@
+<refsect1>
+	<title>Global Configuration</title>
+
+	<variablelist>
+		<varlistentry>
+			<term>Format and Location:</term>
+			<listitem>
+				<para>The configuration file is stored in global system configuration.<sbr/>
+                                        The location is <replaceable>@CMAKE_INSTALL_FULL_SYSCONFDIR@/@VENDOR@/@PRODUCT@/certificates.json</replaceable><sbr/>
+					File format is JSON</para>
+			</listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>Supported options:</term>
+			<listitem>
+				<varlistentry>
+					<term><replaceable>deny</replaceable></term>
+					<listitem>
+						<varlistentry>
+							<listitem>
+								<para><replaceable>JSON boolean</replaceable><sbr/>
+										Deny the certificate if the check against system SSL store was not successful</para>
+							</listitem>
+						</varlistentry>
+					</listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><replaceable>ignore</replaceable></term>
+					<listitem>
+						<varlistentry>
+							<listitem>
+								<para><replaceable>JSON boolean</replaceable><sbr/>
+								Ignore certificate failures, just ignore the certificate</para>
+							</listitem>
+						</varlistentry>
+					</listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><replaceable>deny-userconfig</replaceable></term>
+					<listitem>
+						<varlistentry>
+							<listitem>
+								<para><replaceable>JSON boolean</replaceable><sbr/>
+										If the checks in the global configuration do not accept the certificate do not ask the user</para>
+							</listitem>
+						</varlistentry>
+					</listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><replaceable>certificate-db</replaceable></term>
+					<listitem>
+						<varlistentry>
+							<term><replaceable>JSON array</replaceable></term>
+							<listitem><para>An array of <replaceable>JSON objects</replaceable> with:</para>
+								<varlistentry>
+									<term><replaceable>type</replaceable></term>
+									<listitem>
+										<para><replaceable>JSON string</replaceable><sbr/>
+											a string identifying the hash algorithm used, e.g. <replaceable>sha256</replaceable> <sbr/></para>
+									</listitem>
+								</varlistentry>
+								<varlistentry>
+									<term><replaceable>hash</replaceable></term>
+									<listitem>
+										<para><replaceable>JSON string</replaceable><sbr/>
+												a string of hex integer values representing the certificate hash, e.g. <replaceable>0123456789abcdef</replaceable></para>
+									</listitem>
+								</varlistentry>
+							</listitem>
+						</varlistentry>
+					</listitem>
+				</varlistentry>
+			</listitem>
+		</varlistentry>
+	</variablelist>
+</refsect1>