Add documentation to the new systemd support

diff --git a/unix/vncserver/CMakeLists.txt b/unix/vncserver/CMakeLists.txt
index 9cf0e0ed9fa96ab3c33f0dc72d3fd64888150013..f65ccc7db98cbf359a79087d5ad1d9f4a4a3cfdd 100644 (file)
--- a/unix/vncserver/CMakeLists.txt
+++ b/unix/vncserver/CMakeLists.txt
@@ -15,6 +15,8 @@ install(FILES vncserver-config-defaults vncserver-config-mandatory DESTINATION $
 
 install(FILES vncserver.users DESTINATION ${CMAKE_INSTALL_FULL_SYSCONFDIR}/tigervnc)
 
+install(FILES HOWTO.md DESTINATION ${CMAKE_INSTALL_FULL_DOCDIR})
+
 if(INSTALL_SYSTEMD_UNITS)
   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/vncserver@.service DESTINATION ${CMAKE_INSTALL_FULL_UNITDIR})
   install(PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/vncsession-start DESTINATION ${CMAKE_INSTALL_FULL_LIBEXECDIR})

diff --git a/unix/vncserver/HOWTO.md b/unix/vncserver/HOWTO.md
new file mode 100644 (file)
index 0000000..d5d9b76
--- /dev/null
+++ b/unix/vncserver/HOWTO.md
@@ -0,0 +1,118 @@
+# Changes in recent Tigervnc versions
+Previous Tigervnc versions had a wrapper script called `vncserver`. This script
+could be run as a user manually to start *Xvnc* process. The usage was quite 
+simple as you just run:
+```
+$ vncserver :x [vncserver options] [Xvnc options]
+```
+and that was it. It worked fine for some cases, but far from all. There were issues
+when users wanted to use it in combination with *systemd*. Therefore, the implementation
+had to be changed to comply with *SELinux* and *systemd* rules.
+
+# How to start Tigervnc server
+## Add a user mapping
+With this you can map a user to a particular port. The mapping should be done in 
+`/etc/tigervnc/vncserver.users` configuration file. It should be pretty 
+straightforward. Once you open the file you will see there are some examples, but basically
+the mapping is in form:
+```
+:x=user
+```
+For example you can have
+```
+:1=test
+:2=vncuser
+```
+
+## Configure Xvnc options
+To configure Xvnc parameters, you need to go to the same directory where you did
+the user mapping and open `vncserver-config-defaults` configuration file. This 
+file is for the default Xvnc configuration and will be applied to every user 
+unless any of the following applies:
+* The user has its own configuration in `$HOME/.vnc/config`.
+* The same option with different value is configured in 
+  `vncserver-config-mandatory` configuration file, which replaces the default 
+  configuration and has even a higher priority than the per-user configuration.
+  This option is for system administrators when they want to force particular 
+  *Xvnc* options.
+
+Format of the configuration file is also quite simple as the configuration is
+in form of:
+```
+option=value
+option
+```
+for example:
+```
+session=gnome
+securitytypes=vncauth,tlsvnc
+desktop=sandbox
+geometry=2000x1200
+localhost
+alwaysshared
+```
+See the following manpage for more details: Xvnc(1).
+
+### Note:
+It is recommended to set option specifying the session you want to start. E.g. when
+you want to start GNOME desktop, then you have to use:
+```
+session=gnome
+```
+This should match the name of a session desktop file from `/usr/share/xsessions`
+directory. If you don't specify the session, Tigervnc will try to use the first 
+one it finds, which may or may not work correctly.
+
+## Set VNC password
+You need to set a password for each user in order to be able to start the 
+Tigervnc server. In order to create a password, you just run:
+```
+$ vncpasswd
+```
+You need to run it as the user who will run the server. 
+
+### Note:
+If you used Tigervnc before with your user and you already created a 
+password, then you have to make sure the `$HOME/.vnc` folder created by 
+`vncpasswd` have the correct *SELinux* context. You either can delete this 
+folder and recreate it again by creating the password one more time, or 
+alternatively you can run:
+```
+$ restorecon -RFv /home/<USER>/.vnc
+```
+
+## Start the Tigervnc server
+Finally you can start the server using systemd service. To do so just run:
+```
+$ systemctl start vncserver@:x
+```
+Run this as the root user or:
+```
+$ sudo systemctl start vncserver@:x
+```
+Run it as a regular user in case the user has permissions to run `sudo`. 
+Don't forget to replace the `:x` by the actual number you configured in the
+user mapping file. For example:
+```
+$ systemctl start vncserver@:1
+```
+This starts a Tigervnc server for user `test` with GNOME session.
+
+In case you want your server to be automatically started at boot, you can 
+run:
+```
+$ systemctl enable vncserver@:1
+```
+
+### Note:
+If you previously used Tigervnc and you were used to start it by using 
+*systemd*, then you might need to remove previous *systemd* configuration files
+placed in `/etc/systemd/system/vncserver@.service`, in order to avoid them being
+prioritized by the new systemd service files from latest Tigervnc.
+
+# Limitations
+You will not be able to start a Tigervnc server for a user who is already
+logged into a graphical session. Avoid running the server as the `root` user as
+it's not a safe thing to do. While running the server as the `root` should work 
+in general, it's not recommended to do so and there might be some things which
+are not working properly.