Merge pull request #3 from subzero79/master

Corrections, links and more content

FAQ.rst

@@ -14,7 +14,7 @@ Does |omv| have drivers for my hardware?
 	The Jessie backport kernel 4.9 is the default kernel used by Stretch (Debian 9.3) at the moment, so it provides support for newer hardware.
 
 Can I use a usb flash drive (stick) for installing the system?
-	Yes, but the installation does not have any optimizations to reduce writes into the OS disk. Your usb media will most likely start failing within a few weeks of usage. Most common symptom is basic command execution does not work, denied login, etc.
+	Yes, but the installation does not have any optimizations to reduce writes into the OS disk. Your usb media will most likely start failing within a few weeks of usage. Most common symptom is basic command execution does not work, denied login, etc. More information `here <https://forum.openmediavault.org/index.php/Thread/6438-Tutorial-Experimental-Third-party-Plugin-available-Reducing-OMV-s-disk-writes-al/>`_
 
 What is the file :file:`/etc/openmediavault/config.xml` for?
 	Is the database configuration store file for |omv|. When a change is performed in the |webui|, the config value is stored and/or retrieve by rpc to/from this file. If this is a save change, then mkconf passes the value to the service configuration file and reloads the daemon in case is necessary.
@@ -38,7 +38,7 @@ How can use the default HTTP engine to hold my own web page?
 	Do not modify |omv| default NGINX files. You can place your website configurations at :file:`/etc/nginx/sites-available` and enable it with ``nginx_ensite <SITE>``. Read more information in the `NGINX documentation <http://nginx.org/en/docs/>`_.
 
 Why does the system rewrites a configuration file(s) that I have manually edited?
-	OMV takes full control of some system services. This services include monit, ntp, samba, network, proftpd, nginx, php5-fpm, etc.
+	OMV takes full control of some system services. This services include monit, ntp, samba, network, proftpd, nginx, php5-fpm, etc. Read :doc:`here </various/files>`.
 
 How can I modify an internal value of some service |omv| has control over?
 	Read :doc:`here <various/advset>` for advanced configurations.

features.rst

@@ -7,28 +7,28 @@ General settings
 ----
 **General settings:** Change |webui| listening port, SSL and force SSL. Change admin password
 
-**Notification system:** Integrated into several services in the form of email, these include scheduled tasks, services monitoring, SMART, MDADM and cron-apt. Since |omv| 3.0 is possible to add third party notification systems by using scripts, more information `here <https://github.com/openmediavault/openmediavault/blob/master/deb/openmediavault/usr/share/openmediavault/notification/sink.d/README>`_ and an `example <https://forum.openmediavault.org/index.php/Thread/14919-GUIDE-Use-Telegram-as-notification-service/>`_.
+**Notification system:** Integrated into several services in the form of email using postfix [1]_ backend as MTA, these include scheduled tasks, services monitoring, SMART, MDADM and cron-apt. Since |omv| 3.0 is possible to add also third party notification systems by using scripts, more information `here <https://github.com/openmediavault/openmediavault/blob/master/deb/openmediavault/usr/share/openmediavault/notification/sink.d/README>`_ and real example on how to use it `here <https://forum.openmediavault.org/index.php/Thread/14919-GUIDE-Use-Telegram-as-notification-service/>`_.
 
-**Network configuration:** The webUI provides configuration options for ethernet, wifi (only WPA/WPA2 supported), bond and vlan interfaces. This also includes a panel for firewall configuration.
+**Network configuration:** The web interface provides configuration options for ethernet, wifi (only WPA/WPA2 supported), bond and vlan interfaces. This also includes a panel for firewall configuration.
 
 **Certificates:** Create or import existing SSL and SSH certificates. This certificates can by used for securing the webUI or SSH access. Plugins can use the backend framework to select the available certificates.
 
 **Power Management:** Scheduled power management for hibernation (s5), suspend (s3), shutdown and/or reboot.
 
-**Service Discovery:** Using avahi-daemon is possible to announce the following services SAMBA, NFS, AFP, FTP, web admin panel, to any Linux desktop with file browser that supports it (GNOME, KDE or XFCE for example). OS X can recognise AFP and SAMBA services in the Finder sidebar. To announce SMB to windows clients, samba uses NetBios, not avahi.
+**Service Discovery:** Using avahi-daemon [2]_ is possible to announce the following services SAMBA, NFS, AFP, FTP, web admin panel, to any Linux desktop with file browser that supports it (GNOME, KDE or XFCE for example). OS X can recognise AFP and SAMBA services in the Finder sidebar. To announce SMB to windows clients, samba uses NetBios, not avahi.
 
-**Scheduled Tasks:** Based on cron and anacron the webUI can define tasks to run commands or custom scripts.
+**Scheduled Tasks:** Based on cron the webUI can define tasks for running specific commands or custom scripts at certain time or regular intervals.
 
-**Update Manager:** Display all available package upgrades.
+**Update Manager:** Displays all available packages for upgrade.
 
 Storage
 ----
 
-**S.M.A.R.T.:** Based on smartmontools, It can display advanced information of S.M.A.R.T values in the webUI. It can also schedule health tests as well as send notifications when smart attirbutes values change.
+**S.M.A.R.T.:** Based on smartmontools [3]_, It can display advanced information of S.M.A.R.T values in the webUI. It can also schedule health tests as well as send notifications when smart attirbutes values change.
 
-**RAID Management:** Based on the well known mdadm utility, you can create raid arrays in different configurations. Levels available are linear, 0, 1, 10, 5 and 6. Disks can be removed or array expanded using the web panel
+**RAID Management:** Based linux RAID [4]_, you can create arrays in different 6 different configurations. Levels available are linear, 0, 1, 10, 5 and 6. The array can have disks removed or expanded using the web interface.
 
-**File Systems:** Volume formatting and mounting of disks or arrays.
+**File Systems:** Volume format, device mmount and unmount. More information :doc:`here </various/filesystems>`.
 
 **LVM:** Enhanced by the LVM2 plugin, the system has the capability of formatting disks or partitions as LVM that can be used in volume groups to create logical partitions.
 
@@ -45,28 +45,38 @@ Services
 ----
 
 
-**SMB/CIFS:** SMB sharing protocol using samba as standalone server by default.
+**SMB/CIFS:** SMB sharing protocol using Samba [5]_ as standalone server by default.
 
-**FTP:** Service based on proftpd. Intended for accessing shares from remote locations.
+**FTP:** Service based on proftpd [6]_. Intended for accessing shares from remote or local.
 
-**RSync:** Server daemon. Shared folders can be defined as rsync modules. With scheduled tasks, rsync client can be configured for push and/or pull jobs.
+**RSync:** Server daemon. Shared folders can be defined as rsyncd modules. With scheduled tasks, rsync client can be configured for push or pull jobs.
 
-**NFS:** Network file system protocol.
+**NFS:** Network file system protocol [7]_.
 
-**SSH:** Remote shell access with SFTP configured by default. `Guide <https://forum.openmediavault.org/index.php/Thread/7822-GUIDE-Enable-SSH-with-Public-Key-Authentication-Securing-remote-webUI-access-to/>`_ on how to configure ssh in |omv|.
+**SSH:** Remote shell access using openssh [8]_.
 
 **TFTP:** A basic configuration panel is provided. This can complement a PXE server to deploy local network installations.
 
 .. note::
 
-	In |omv| version 4 the TFTP has been removed from core, and it now can be installed as an official plugin.
+	In |omv| version 4 the TFTP has been removed from core, and now it can be installed as an official plugin.
 
 Diagnostics
 ----
-**Dashboard:** By default the server comes with four information widgets. Network interfaces, System, Filesystem and service/daemon status.
+**Dashboard:** By default the server comes with four information widgets. Network interfaces, System, Filesystem and service/daemon status. The dashboard panel can have widgets added using the plugin framework.
 
-**System information:** The panel displays four tabs with system information generated from top and usage graphs from rrdcached.
+**System information:** The panel displays four tabs with system information and statistics graphs.
 
-**System Logs:** Interface to view and download logs from syslog, boot, message, auth, ftp, rsync and samba. Plugins can attach their logs here using the framework.
+**System Logs:** Interface to view and download logs from syslog, journalctl, message, auth, ftp, rsync and samba. Plugins can attach their logs here using the framework.
 
-**Services:** View status (enabled/disabled and running/not running) of services. Detailed information is provided by default for Samba, FTP and SSH. Plugins can use this tab to integrate their service information.
+**Services:** View status (enabled/disabled and running/not running) of services. Detailed information is provided by default for Samba, FTP and SSH. Plugins can use this tab to integrate their service information also.
+
+
+.. [1] http://postfix.org
+.. [2] https://www.avahi.org/
+.. [3] https://www.smartmontools.org/
+.. [4] https://raid.wiki.kernel.org/index.php/RAID_setup
+.. [5] https://www.samba.org/
+.. [6] http://www.proftpd.org/
+.. [7] http://nfs.sourceforge.net/
+.. [8] https://www.openssh.com/

index.rst

@@ -28,6 +28,7 @@ plugins are available via the `OMV-Extras repository <http://omv-extras.org/>`_.
    prerequisites
    installation/index
    features
+   services
    plugins
    FAQ
    support

services.rst

@@ -0,0 +1,142 @@
+Services
+####
+
+
+Samba
+====
+
+Samba server comes from Debian software repositories. Openmediavault developer does not mantain this package, all bug, hotfixes and features come from Debian. Advanced features like spotlight server or time machine support is not available because they have not reach yet stable Debian or the Debian developers have not made it available in their build.
+
+General
+^^^^
+
+The server configures samba as standalone mode. The default global configuration is the following:
+
+..  code-block:: conf
+
+	[global]
+	workgroup = HOME
+	server string = %h server
+	dns proxy = no
+	log level = 0
+	syslog = 0
+	log file = /var/log/samba/log.%m
+	max log size = 1000
+	syslog only = yes
+	panic action = /usr/share/samba/panic-action %d
+	encrypt passwords = true
+	passdb backend = tdbsam
+	obey pam restrictions = no
+	unix password sync = no
+	passwd program = /usr/bin/passwd %u
+	passwd chat = *Enter\snew\s*\spassword:* %n\n *Retype\snew\s*\spassword:* %n\n *password\supdated\ssuccessfully* .
+	pam password change = yes
+	socket options = TCP_NODELAY IPTOS_LOWDELAY
+	guest account = nobody
+	load printers = no
+	disable spoolss = yes
+	printing = bsd
+	printcap name = /dev/null
+	unix extensions = yes
+	wide links = no
+	create mask = 0777
+	directory mask = 0777
+	use sendfile = yes
+	aio read size = 16384
+	aio write size = 16384
+	null passwords = no
+	local master = yes
+	time server = no
+	wins support = no
+
+
+Shares are configured in this way:
+
+..  code-block:: conf
+	
+	[MyDocuments]
+	path = /media//dev/disk/by-label/VOLUME1/Documents/
+	guest ok = no
+	read only = no
+	browseable = yes
+	inherit acls = yes
+	inherit permissions = no
+	ea support = no
+	store dos attributes = no
+	printable = no
+	create mask = 0755
+	force create mode = 0644
+	directory mask = 0755
+	force directory mode = 0755
+	hide dot files = yes
+	valid users = "john"
+	invalid users = 
+	read list = 
+	write list = "john"
+
+
+You can add extra options in the general and share configuration at the bottom, where you have a multi line text field. This options are hardcoded in the mkconf script but they can be changed using :doc:`environmental variables </various/advset>`
+
+Privileges
+^^^^
+
+The login access in samba is configured using privileges. This means they will not act in the file system layer they will run in the samba authentication layer. From there the access can be controlled to be read only or read/write access and guest account access. This is done with the PRIVILEGES button in the shared folder section not the ACL. 
+Privileges only gets only login access and from there determines if user can read or write. If write access is enabled and files/folders have restricted permissions then you will still not be able to write to folder using samba.
+
+Share types
+^^^^
+**Non-public (Private):** *Login always required, Guest Allowed denied*::
+
+	guest ok = no
+	valid users = User1, User2, @Group1, @Group2 ## this will deny all none authorized users
+	read list = User1, @Group1
+	write list = User2, @Group2
+
+This means that every user will have to provide valid OMV credentials to access that share. Also this type of shares requires at least one definition of a valid user, otherwise the directive would be empty. THIS WILL ALLOW EVERY USER TO LOG INTO THE SHARE.
+
+
+**Semi-public:** 
+*When login is not provided, the guest user is used. This is the "guest allowed" option from the samba share option*::
+	guest ok = yes
+	read list = User1, @Group1
+	write list = User2, @Group2
+
+Notice here if you have a user that you have not set up privileges for (thank means blank tick boxes) he will be able to login anyway and have write access.
+
+**Public only:** *The guest user is always used. This is the Guest Only option in the samba share configuration.*:: 
+
+	guest ok = yes
+	guest only = yes
+
+With these options valid, read only and write user directives will be ignored when mkconf regenerates the ``/etc/samba/smb.conf`` file.
+
+.. note::
+	- The guest account is mapped to system account nobody, he doesn’t belong to group users, thus he HAS BY DEFAULT NO WRITE ACCESS just READ. This is can be reverted modifying the POSIX permissions of the share to 777.
+	- These directives are NOT ACL
+
+
+Questions:
+^^^^
+How do I enter credentials in a semi-public share?
+	In most cases the user will always be logged as guest.
+	You have to use windows map network drive feature to provide other login credentials different from guest.
+	In Mac OS X you can use CMD+K (if you are in Finder)
+
+Why the login keeps saying access denied?
+	This is more likely caused by two things: Permission issue (ACL or non default POSIX permission mode/ownership). You need to fix the permissions in the shared folder. Samba runs as privileged (root) user, even so if parts of path don't have adecuate permissions you can still get access denied. 
+
+Why I can't edit files that other users have created?
+	The default umask in samba is 644 for files. So to enable flexible sharing tick Enable permission inheritance in the samba share settings this will force 664 creation mode. Files created previously need to change their permission mode. Use reset permission utility. Check also that you don't have read only enabled. This option overrides privileges and POSIX.
+
+
+Netatalk
+====
+
+FTP
+====
+
+RSync
+====
+
+NFS
+===

various/apt.rst

@@ -4,7 +4,7 @@ Software
 Overview
 ----
 
-|omv| is under a Debian distribution. It uses apt to install packages. All
+Openmediavault is a Debian based distribution. It uses apt to install packages. All
 standard Debian packages are upgraded using the official Debian mirrors. |omv|
 packages are upgraded using the http://packages.openmediavault.org repository.
 

various/files.rst

@@ -0,0 +1,27 @@
+Configuration files
+=====
+
+
+The following is the list of files you should not edit by hand. |omv| has complete control over these files and any changes will be overwrriten on demand.
+
+**Filesystem:** ``/etc/fstab`` This file contains all mount entries, physical and network ones. |omv| identifies them by using the «openmediavault» tags, in between those you should not delete entries or change options. Any new mount drive or network entry will rewrite fstab in between those lines, reverting any changes you have done. Please refer :doc:`here </various/fs_env_vars>` for editing options of fstab entries. You can add any content you want outside the tags.
+
+**Network:** ``/etc/network/interfaces`` The explanation is already in the :doc:`FAQ </FAQ>`
+
+**NGINX:** ``/etc/nginx/openmediavault-webgui.d/security.conf`` ``/etc/nginx/sites-enabled/openmediavault-webgui`` 
+
+**PHP5-FPM:** ``/etc/php5/fpm/pool.d/openmediavault-webgui.conf``
+
+**POSTFIX:** Any configuration files by postfix should not be edited unless you know what you are doing. You run the risk of breaking the notification system.
+
+**MONIT:** ``/etc/monit/monitrc`` ``/etc/monit/conf.d/openmediavault-{servicename}``
+
+**SAMBA:** ``/etc/samba/smb.conf`` Use the extra options in general or by share to define directives not present in the webUI.
+
+**FTP:** ``/etc/proftpd/proftpd.conf`` Use the extra options in general or per share to add directives not available in the webUI.
+
+**NFS:** ``/etc/exports`` Use environmental variables if you want to change the pseudo root filesystem options for NFSv4.
+
+**APT**
+	- ``/etc/apt/sources.list`` This is default debian repository server file. Read more information :doc:`here <apt>`.
+	- ``/etc/apt/sources.list.d/openmediavault.list`` This is the server package repository for OMV.