Relocate services into seperate files.

Signed-off-by: Volker Theile <volker.theile@openmediavault.org>

administration/index.rst

@@ -8,5 +8,5 @@ Administration
 
    certificates
    access_rights_management
-   services
+   services/index
    cron

administration/services/ftp.rst

@@ -0,0 +1,89 @@
+FTP
+####
+
+Overview
+----
+
+On top of the proftpd debian package, |omv| uses the vroot module by Castaglia. The server is configured using a DefaultRoot for this folder ``/srv/ftp``. Adding folders to the chroot is done by using vroot aliases.
+
+This is the default behavoiour of the FTP server and cannot be changed. The vroot default path can be changed with environmental variables. The chroot also prevent symlinks for escaping that path, however you can use symlinks that point inside the chroot.
+
+So any time you add a shared folder to the FTP, OMV will create first a vroot alias:::
+
+	<IfModule mod_vroot.c>
+	  VRootAlias "/media/dev-disk-by-label-VOLUME1/videos" "Videos"
+	</IfModule>
+
+
+Then that alias will have privileges assigned:::
+
+	<Directory /Videos>
+	  <Limit ALL>
+	    AllowUser OR omvUser
+	    DenyAll
+	  </Limit>
+	  <Limit READ DIRS>
+	    AllowUser OR omvUser
+	    DenyAll
+	  </Limit>
+	</Directory>
+
+By default you're not allowed to write in the when you login, this means you cannot create folders in the landing directory, you have to enter one of the shared folders. Also due to the nature of the chroot, creating top level folders is pointless since they will be actually stored in /srv/ftp and not in the media disks.
+
+Remote Access
+----
+
+FTP is a protocol intended for use in LAN and WAN. For accessing WAN it is required to forward the server port (default 21) and the passive range to the |omv| server.
+
+Anonymous Login
+-----
+
+Disabled by default, the anonymous user is mapped to the system user ftp and nogroup. There is no write access for anonymous and this is configured in the ``/etc/proftpd/proftpd.conf`` file and cannot be changed as is hard coded into the default configuration script of the server. In this case there is no environmental variable to change that behaviour::
+
+	<Anonymous ~ftp>
+	  User ftp
+	  Group nogroup
+	  UserAlias anonymous ftp
+	  DirFakeUser on ftp
+	  DirFakeGroup on ftp
+	  RequireValidShell off
+	  <Directory *>
+	    HideFiles (welcome.msg)
+	    HideNoAccess on
+	    <Limit WRITE>
+	      DenyAll
+	    </Limit>
+	  </Directory>
+	</Anonymous>
+
+
+FTP(S/ES)
+----
+|omv| provides two SSL/TLS modes for encrypting the FTP communication implicit and explicit FTPS.
+
+The differences and features are explained `here <https://en.wikipedia.org/wiki/FTPS>`_ and `here <http://www.jscape.com/blog/bid/75602/Understanding-Key-Differences-Between-FTP-FTPS-and-SFTP>`_.
+
+Enabling FTP over SSL/TLS requires first that you create or import a certificate in the corresponding section. Once the certficate is there you can choose it from SSL/TLS section in FTP. The default FTPS of the server is explicit, you can click the checkbox to enable implicit. If you choose implicit make sure you forward port 900 in your router to port 21 in your NAS server if you're accessing from WAN, otherwise the client will probably display ECONREFUSED.
+
+Tips
+----
+
+Login Group
+	By default all |omv| users created in the |webui| can gain login into FTP. You can restrict to read only or read write, there is no deny access, but the user has no privileges he would not see that folder. If you want to add a layer of extra security for the login, you can create a control group to restrict login to FTP. You first create a group for example ftp_users, then at the end of the general extra options of the server we add:
+
+	.. code-block:: guess
+
+		​<Limit LOGIN>
+		    DenyGroup !ftp_users
+		</Limit>
+
+	Only users members of that particular group will be able to log into the FTP server.
+
+Home Folders
+	There is not straightforward way of doing this in the |webui|, but if you really need home folders for FTP, you can change the default vroot path with environmental variable ``OMV_PROFTPD_MODAUTH_DEFAULTROOT=“~”``.
+	What will happen here if users will log in straight into their home folders. If you add shared folders to the server they will be displayed inside the user home folder plus any other folder present in their home folder.
+
+LetsEncrypt
+	Just import your LE certificate in the ``General->Certificates->SSL`` `section <certificates.html#ssl-secure-socket-layer>`_. Then in the TLS/SSL tab, select the imported cert from the dropdown menu. Do not enable implicit ssl. You need also to add the chain file. So in the extra option field text add:
+
+	``TLSCACertificateFile <yourpathtoLE>/etc/letsencrypt/live/<yourdomain>/chain.pem``

administration/services/index.rst

@@ -0,0 +1,14 @@
+.. _services_index:
+
+Services
+########
+
+.. toctree::
+   :maxdepth: 2
+
+   samba
+   ftp
+   nfs
+   ssh
+   rsync
+   netatalk

administration/services/netatalk.rst

@@ -0,0 +1,55 @@
+Netatalk (plugin)
+=====
+
+Overview
+----
+Netatalk software was expected to reach version 3.x with Debian Jessie. Unfortunatly due to some unresolved issue with the maintainers, Debian team `opted <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=690227>`_ to leave it out of Jessie and future releases. Debian Wheezy was the latest release with netatalk. To avoid loosing netatalk as a plugin |omv| uses a debianized source of netatalk 3.x maintained by Adrian Knoth [1]_. Openmediavault does not maintain this software.
+
+Configuration
+----
+The server panel provides minimal options to the server, but it has an extra field in case you need `more directives <http://netatalk.sourceforge.net/3.1/htmldocs/afp.conf.5.html>`_. The default configuration file is located in ``/etc/netatalk/afp.conf``. This is the default global section:
+
+.. code-block:: guess
+
+	[Global]
+	max connections = 20
+	mac charset = MAC_ROMAN
+	unix charset = LOCALE
+	guest account = nobody
+	uam list = uams_dhx.so,uams_dhx2.so
+	save password = no
+
+Netatalk provides PAM modules, so a change of password in terminal or web interface should be reflected inmediately in AFP login.
+
+Shared Folders
+----
+The plugin uses the privileges database, so in the same way |omv| configures Samba shares, the login is controlled using valid, read and write directives in the software layer, not the filesystem. This is an example of a share in netatalk with default options:
+
+.. code-block:: guess
+
+	[Documents]
+	path = /media/dev-disk-by-label-VOLUME1/documents
+	read only = no
+	unix priv = yes
+	file perm = 0664
+	directory perm = 0775
+	umask = 0002
+	invisible dots = no
+	time machine = no
+	valid users = "mike"
+	invalid users =
+	rolist =
+	rwlist = "mike"
+
+Password
+	In case you don't want to use privileges you can assign a single password (no username) to the share.
+
+Time Machine
+	Support for the Apple backup software was added in netatalk 2.x, and improved in 3.x. Just check the box in the share options to make announce an individual share as a time machine server.
+
+Guest Access
+	You can select guest access which by default is read only. A second checkbox is provided for giving write access to guest.
+
+Quota
+	You can define a size limit, in case you have multiple time machine volumes and want to prevent them to fill up the data drives.
+.. [1] https://github.com/adiknoth/netatalk-debian

administration/services/nfs.rst

@@ -0,0 +1,78 @@
+NFS
+####
+
+Overview
+----
+
+The configuration of the server is done using the common `NFS guidelines <https://help.ubuntu.com/community/SettingUpNFSHowTo>`_. Shared folders are actually binded to the /export directory. You can check by examining the ``/etc/fstab`` file after you have added a folder to the server. All NFS server configured folders are in /etc/exports as follows:::
+
+	/export/Shared_1 (fsid=1,rw,subtree_check,secure,root_squash)
+	/export/Videos 10.10.0.0/24 (fsid=2,rw,subtree_check,secure,nroot_squash)
+	/export (ro,fsid=0,root_squash,no_subtree_check,hide)
+
+The first two lines are examples, the last line is the NFSv4 pseudo file system. [1]_ [2]_
+
+
+Server Shares
+----
+
+The following options are available to configure from the |webui|:
+
+	- **Shared folder:** Select a folder, the system will add an bind entry to fstab, mount that bind and add it to /etc/exports file
+	- **Client:** Enter a single ip, host or network CIDR notation. Only one entry is allowed at the moment. You can leave it empty if you do not want network security.
+	- **Privilege:** This will append read write (rw) or read-only (ro) to ``/etc/exports``. [3]_
+	- **Extra options:** Add options according the `exports manual <https://linux.die.net/man/5/exports>`_. If squash options are not specified, the mkconf script will add ``root_squash`` by default which is not displayed in the text field.
+
+	The server also shares by default the pseudo root filesystem of /exports as NFSv4.
+
+Clients
+----
+To access NFS shares using any debian derived linux distro:
+
+* Mount as NFSv4 all folders in ``/export/`` in ``/mnt/nfs``::
+
+  $ mount 172.34.3.12:/ /mnt/nfs
+
+* Mount as NFSv3 all folders inside ``/export`` in ``/mnt/nfs``::
+
+  $ mount 172.34.3.12:/export /mnt/nfs
+
+* Mount as NFSv3 the folder ``/export/Videos`` in ``/mnt/nfs``::
+
+  $ mount 172.34.3.12:/export/Videos /mnt/nfs
+
+* Mount as NFSv4 the folder ``/export/Videos`` in ``/mnt/nfs``::
+
+  $ mount 172.34.3.12:/Videos /mnt/nfs
+
+Check your distro on how to proceed with different NFS versions.
+
+NFSv4 Pseudo filesystem
+----
+The default /export folder is shared with this default options ``ro,wdelay,root_squash,no_subtree_check,fsid=0`` only available to change via environmental variables, so be aware that mounting this path you will encounter permission problems.
+
+Permissions
+----
+NFS relies on uid/gid matching at the remote/local filesystem and it doesn't provide any authentication/security at all. Basic security is provided by using network allow, and squash options. If you want extra security in NFS, you will need to configure it to use kerberos ticketing system.
+
+Tips
+----
+Macos/OSX
+	If you want to mount your NFS exports, add insecure in extra opions or use ``resvport`` in the command line.
+
+	Example::
+
+	$ sudo mount -t nfs -o resvport,rw 192.168.3.1:/export/Videos /private/nfs
+
+Debian
+	Debian distributions (and many others) always include the group users with ``gid=100`` by default, if you want to resolve permissions easily for all users of a PC using linux add ``anonuid=100`` in extra options. This will force all mounts to use that gid.
+
+Symlinks
+	This are not followed outside of their export path, so they have to be relative.
+
+Remote access
+	NFS was designed to be used as a local network protocol. Do not expose the NFS server to the internet. If you still need access use a VPN.
+
+.. [1] https://help.ubuntu.com/community/NFSv4Howto#NFSv4_without_Kerberos
+.. [2] https://www.centos.org/docs/5/html/5.1/Deployment_Guide/s3-nfs-server-config-exportfs-nfsv4.html
+.. [3] This is not standard |omv| privileges as in the shared folder section

administration/services/rsync.rst

@@ -0,0 +1,86 @@
+RSync
+#####
+
+The server can be configured to act as a client to pull and push data to remote locations as well as act an rsync daemon server, where other clients can retrieve or store data from/to the server. In rsync languague, the shared folders are called modules. Since |omv| version 3.0 is possible now to create remote rsync jobs using ssh as transport shell.
+
+The rsync is divided in two tabs
+
+Jobs (client)
+----
+Based on cron, the tasks can be configured to run at certain time or make it repetive. A few of the options explained:
+
+Type
+	- Local: This will run an rsync in between two internal folders of the server. For example you can use this to move data across different disks in your system
+	- Remote: This will deactivate destination folder, and instead you'll need to place a destination server address. You can select here:
+
+		Mode (remote)
+			- Push: store contents to a remote server
+			- Pull: Retrieve contents from a remote server
+
+	Selecting one or the other will invert the folder as source or destination, the same as the server address.
+
+Destination/Source Shared Folder
+	Choose a shared folder where you want the contents to be stored (pull) or you want the contents from that folder to be sent to a remote server (push)
+
+Destination/Source Server
+	You need to put address server host or ip.
+
+	Examples:
+
+	If you are targeting the job against an rsync daemon server:
+	::
+		rsync://10.10.10.12/ModuleName
+		username@10.10.10.12::ModuleName
+		rsync://username@10.10.10.12:873/ModuleName
+
+	If you are going to connect to another server just using ssh with public key:
+	::
+		username@10.10.0.12:/srv/dev-disk-by-label-VOLUME1/Documents
+
+.. warning::
+	When the rsync task is configured using ssh with PKA, the script that runs the jobs is non-interactive, this means there cannot be a neither a passphrase for the private key or a login password. Make sure your private is not created with a password (in case is imported). Also make sure the remote server can accept PKA and not enforce password login.
+
+**Authentication (remote)**
+
+	- **Password**: For the remote rsync daemon module. Is not the username login password defined in the Rights Management section of the server. Read ahead in server tab.
+	- **Public Key**: Select a key. These are created/imported from ``General->Certificates->SSH`` `section <certificates.html#ssh-secure-shell>`_.
+
+There are options are available which are the most commonly used in rsync. At the end there is an extra text field where you add more `options <http://linux.die.net/man/1/rsync>`_.
+
+Server
+----
+
+This is the place for configuring the rsync daemon and it's modules (shared folder).
+
+Settings
+	Change listening port of the daemon and add extra configurations `directives <https://www.samba.org/ftp/rsync/rsyncd.conf.html>`_ text field.
+
+Modules
+	This is where you add shared folders to be available to the daemon. The options are explained in the module web panel. If you want to protect the modules you can select the next tab and choose a server username and establish a password. Be aware the password is only for the modules, is not the linux password. Documentation for the extra options for the modules is provided by rsyncd manual.
+
+Configuration
+	The server makes the tasks run by placing them in ``/etc/cron.d/openmediavault-rsync`` in one line per job. You can see the cron time at the beginning, then user (root) and target file that holds the actual rsync file with the final command. The files are stored in ``/var/lib/openmediavault/cron.d/``, prefixed with ``rsync`` and a <uuid>. A default ssh rsync job looks like this.
+
+.. code-block:: shell
+
+	#!/bin/sh
+	# This configuration file is auto-generated.
+	# WARNING: Do not edit this file, your changes will be lost.
+	. /usr/share/openmediavault/scripts/helper-functions
+	cleanup() {
+	  omv_kill_children $$
+	  rm -f /var/run/rsync-05260f23-5098-4f07-9250-0b38b923ac7f
+	  exit
+	}
+	[ -e /var/run/rsync-05260f23-5098-4f07-9250-0b38b923ac7f ] && exit 1
+	if ! omv_is_mounted "/srv/dev-disk-by-label-VOLUME1/" ; then
+	    omv_error "Source storage device not mounted at </srv/dev-disk-by-label-VOLUME1>!"
+	    exit 1
+	fi
+	trap cleanup 0 1 2 5 15
+	touch /var/run/rsync-05260f23-5098-4f07-9250-0b38b923ac7f
+	omv_log "Please wait, syncing </srv/dev-disk-by-label-VOLUME1/backupdir/> to <username@backupserver.com:/opt/backup> ...\n"
+	eval $(ssh-agent) >/dev/null
+	ssh-add /etc/ssh/openmediavault-484a6837-5170-468c-aa8f-0e3cb92a641e >/dev/null
+	rsync --verbose --log-file="/var/log/rsync.log" --rsh "ssh -p 22" --recursive --times --archive --perms '/srv/dev-disk-by-label-VOLUME1/backupdir/' 'username@backupserver.com:/opt/backup' & wait $!
+	omv_log "\nThe synchronisation has completed successfully."