Merge pull request #205 from NethServer/upgrade-ns6

Add upgrade chapter

NethServer/dev#5234

administrator-manual/en/accounts.rst

@@ -66,6 +66,7 @@ configure.
 In the end, if the SMB file sharing protocol support is not required, an
 LDAP provider is the best choice.
 
+.. _ldap-local-accounts-provider-section:
 
 OpenLDAP local provider installation
 ------------------------------------
@@ -75,7 +76,7 @@ From the :guilabel:`Software Center` install the module named
 package is automatically configured and the administrator will be able to manage
 users and groups from the :guilabel:`User and groups` page.
 
-
+.. _ad-local-accounts-provider-section:
 
 Samba Active Directory local provider installation
 --------------------------------------------------
@@ -168,7 +169,7 @@ Configure MAC Address Spoofing for Virtual Network Adapters
 
 https://technet.microsoft.com/en-us/library/ff458341.aspx
 
-
+.. _join-existing-ad-section:
 
 Join an existing Active Directory domain
 ----------------------------------------

administrator-manual/en/backup.rst

@@ -179,10 +179,11 @@ Restore installed modules
 
 By default the process of configuration restore will also restore all previously installed modules.
 
-To avoid the reinstallation, execute this command before the restore: ::
+To skip the automatic installation, execute the command with the
+``--no-reinstall`` argument: ::
+
+    restore-config --no-reinstall
 
-  config setprop backup-config reinstall disabled
-     
 .. _backup_customization-section:
 
 Data backup customization

administrator-manual/en/index.rst

@@ -18,8 +18,8 @@ Administrator Manual
 
         Official site: `www.nethesis.it <http://www.nethesis.it>`_
 
-Release notes 7
----------------
+Release notes |version|
+-----------------------
 
 .. toctree::
    :maxdepth: 2
@@ -110,6 +110,7 @@ Appendix
    :maxdepth: 1
 
    migration
+   upgrade
    license
 
 

administrator-manual/en/release_notes.rst

@@ -1,8 +1,8 @@
 =======================
-Release notes |release|
+Release notes |version|
 =======================
 
-|product| release |release|
+|product| release |version|
 
 This release is based on CentOS 7.3:
 https://wiki.centos.org/Manuals/ReleaseNotes/CentOS7
@@ -25,6 +25,12 @@ Upgrading RC4 to Final
 To upgrade a RC4 installation to Final, go to the :guilabel:`Software Center`
 page and follow Server Manager instructions.
 
+Upgrading |product| 6 to |product| |version|
+--------------------------------------------
+
+It is possible to upgrade the previous major release of |product| to |version|,
+with a backup/restore strategy. See the :ref:`upgrade-section` for details.
+
 .. _server_manager-section:
 
 Server Manager access
@@ -50,8 +56,8 @@ If you want to enable user shared mailbox, execute: ::
 Changelog
 ---------
 
-|product| `Final changelog <https://github.com/NethServer/dev/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20milestone%3Av7%20closed%3A2017-01-17T00%3A00%3A00Z..2017-01-30%20>`_
-
+* `ISO Final changelog <https://github.com/NethServer/dev/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20milestone%3Av7%20closed%3A2017-01-17T00%3A00%3A00Z..2017-01-30>`_ (from 2017-01-17 to 2017-01-30)
+* `Rolling release changelog <https://github.com/NethServer/dev/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20milestone%3Av7%20closed%3A2017-01-30T23%3A59%3A59Z..2024-06-30>`_ (from 2017-01-30 to 2024-06-30)
 
 Known bugs
 ----------
@@ -60,6 +66,7 @@ Known bugs
 
 * Discussions around `possible bugs <http://community.nethserver.org/c/bug>`_
 
+.. _discontinued-section:
 
 Discontinued packages
 ---------------------

administrator-manual/en/upgrade.rst

@@ -0,0 +1,144 @@
+.. index:: upgrade
+
+.. _upgrade-section:
+
+========================
+Upgrade from |product| 6
+========================
+
+The upgrade from |product| 6 to |product| |version| can be achieved using
+the **backup and restore** procedure.
+
+.. warning::
+
+    Before running the migration procedure, read carefully all the sections of this
+    chapter.
+    Please also read :ref:`discontinued-section`.
+
+#. Make sure to have an updated backup of the original installation.
+
+#. Install |product| |version| and complete the initial steps using the first configuration wizard.
+   The new machine must have the same hostname of the old one, while the domain name
+   can be changed to fit the accounts provider needs.
+
+#. Restore the configuration backup using the web interface.
+   If any error occurs, check the :file:`/var/log/messages` log file for further information: ::
+
+       grep -E '(FAIL|ERROR)' /var/log/messages
+
+#. If needed, change the network configuration accordingly to the new hardware.
+
+#. Complete the restore procedure with the following command: ::
+
+    restore-data
+
+#. Check the restore log: ::
+
+    cat /var/log/restore-data.log
+
+Accounts provider
+=================
+
+There are different upgrade scenarios, depending on how the source machine was configured.
+
+* If the source system was a NT Primary Domain Controller (Samba server role was
+  :guilabel:`Primary Domain Controller` -- PDC) or a standalone file server
+  (role was :guilabel:`Workstation` -- WS), refer to :ref:`pdc-upgrade-section`.
+
+* If the source system was joined to an Active Directory domain (Samba server
+  role was :guilabel:`Active Directory member` -- ADS), refer to
+  :ref:`ads-upgrade-section`.
+
+* In any other case, the LDAP server is upgraded automatically to *local
+  LDAP accounts provider*, preserving existing users, passwords and groups.
+
+.. _pdc-upgrade-section:
+
+Primary Domain Controller and Workstation upgrade
+-------------------------------------------------
+
+After the restore procedure, the following manual steps are required to promote
+the LDAP server (nethserver-directory package) to a *local Active Directory*
+accounts provider.
+
+An additional, free, IP address from the *green* network is required by the
+Linux container to run the local Active Directory accounts provider.
+
+For instance:
+
+* nethserver IP (green): ``192.168.98.252``
+* free additional IP in green network: ``192.168.98.7``
+
+Verify it is really a free IP:
+
+::
+
+    # ping 192.168.98.7
+    PING 192.168.98.7 (192.168.98.7) 56(84) bytes of data.
+    From 192.168.98.252 icmp_seq=1 Destination Host Unreachable
+
+Ensure there is a working Internet connection:
+
+::
+
+    # curl -I http://packages.nethserver.org/nethserver/
+    HTTP/1.1 200 OK
+
+
+Set the IP for nsdc container and run the upgrade event:
+
+::
+
+    config set nsdc service IpAddress 192.168.98.7
+    signal-event nethserver-directory-ns6upgrade
+
+For more information about the local Active Directory accounts provider, see
+:ref:`ad-local-accounts-provider-section`.
+
+.. _ads-upgrade-section:
+
+Active Directory member upgrade
+-------------------------------
+
+The system upgrade procedure tries to reuse the AD machine credentials contained
+in the configuration backup.
+
+To upgrade the server correctly:
+
+- the **machine credentials must be still valid**
+
+- the AD domain controller must be reachable
+
+At the end of the restore procedure Users and Groups page could fail to connect
+AD. To fix the credentials used by Server Manager to access AD, go to "Accounts
+provider > Advanced settings" page. For more information see
+:ref:`join-existing-ad-section`.
+
+.. warning:: Mail aliases from AD server are not imported automatically!
+
+Shared folders
+==============
+
+Shared folders have been split into two packages:
+
+- "Shared folders" page configures only Samba shares, it provides data access
+  using CIFS/SMB protocol and can be used to share files among Windows and Linux
+  workstations
+
+- The "Virtual hosts" panel provides HTTP and FTP access, it has been designed
+  to host web sites and web applications
+
+Every shared folder with web access configured in |product| 6 can be migrated to
+a virtual host directly from the web interface by selecting the action
+:guilabel:`Migrate to virtual host`. After the migration, data inside the new
+virtual host will be accessible using only FTP and HTTP protocols.
+
+
+Owncloud and Nextcloud
+======================
+
+In |product| |version|, Owncloud has officially been replaced by Nextcloud.
+
+However Owncloud 7 is still available to avoid service disruption after the upgrade.
+Migration from Owncloud to Nextcloud is manual and can be arranged according
+to user's need.

developer-manual/en/index.rst

@@ -44,7 +44,6 @@ Developer Manual
    backup
    gateway
    ips
-   samba
 
 .. toctree::
    :maxdepth: 2

developer-manual/en/modules

@@ -17,6 +17,7 @@ nethserver-httpd-admin
 nethserver-virtualhosts
 nethserver-getmail
 nethserver-nextcloud
+nethserver-samba
 nethserver-squid
 nethserver-suricata
 nethserver-webtop5

developer-manual/en/nethserver-samba.rst

@@ -0,0 +1,97 @@
+================
+nethserver-samba
+================
+
+File and print server for a MS-Windows network based on `Samba
+<http://samba.org>`_.
+
+
+Configuration database
+======================
+
+Example: ::
+
+ smb=service
+    ...
+    Workgroup=
+    NetbiosAliasList=
+    DeadTime=10080
+    WinsServerStatus=disabled
+    WinsServerIP=
+    UseCups=enabled
+    UseClientDriver=yes
+
+* ``Workgroup``
+  The old workgroup name or NT-style domain name, depending on the actual
+  security mode (see also nethserver-sssd for implementation); if empty use the
+  first domain name component from the machine FQDN.
+
+* ``NetbiosAliasList``
+  See ``netbios aliases`` parameter in smb.conf(5) manpage.
+
+* ``DeadTime`` (days)
+  See ``deadtime`` parameter in smb.conf(5) manpage.
+
+* ``WinsServerStatus``
+  if ``enabled`` act as a WINS server.
+
+* ``WinsServerIP`` *ipaddress*
+  if ``WinsServerStatus`` is ``disabled``, ``nmbd`` will register with the given
+  WINS server. See ``wins server``, ``remote announce``, ``remote browse sync``
+  parameters in smb.conf(5) manpage.
+
+* ``UseCups {enabled,disabled}``
+  Use cups as printing server.
+
+* ``UseClientDriver {yes,no}``
+  See ``use client driver`` parameter in smb.conf(5) manpage.
+
+
+Accounts database
+=================
+
+Only records with type ``ibay``.
+
+Properties:
+
+* ``SmbStatus``
+  if ``enabled``, activates ibay sharing through SMB protocol
+* ``SmbProfileType`` select the profile template to apply to the share (optional).
+    The template path must be placed into ``/etc/e-smith/templates/etc/smb.conf/`` and prefixed by ``ibay-``.
+    Eg: ``default`` profile is located at ``/etc/e-smith/templates/etc/smb.conf/ibay-default``.
+
+* ``SmbRecycleBinStatus``: enable or disable the recycle bin; when a file is deleted it is moved inside the recycle bin.
+* ``SmbShareBrowseable``: controls the visibility of the shared folder, default is ``enabled``.
+
+Example: ::
+
+ iba1=ibay
+    AclRead=domadmins,admin
+    AclWrite=domadmins,admin
+    Description=test
+    GroupAccess=rw
+    OtherAccess=r
+    OwningGroup=locals
+    SmbGuestAccessType=none
+    SmbRecycleBinStatus=disabled
+    SmbShareBrowseable=enabled
+    SmbStatus=enabled
+
+Shared folder profile
+=====================
+
+.. note:: Shared folder profile is not related to "Roaming profiles"!
+
+Ibays serve different purposes and ``smb.conf`` provides a lot of parameters to
+configure a Samba share. It's difficult to find a combination of parameters that
+can fit all the possible requirements.  Thus an ibay configuration adheres to a
+*profile*.
+
+An *ibay profile* is a ``smb.conf`` sub-template that expands a cohesive set of
+share parameters. Each ibay has ``SmbProfileType`` prop that selects the
+template to apply to the ibay. The template path must be placed into
+``/etc/e-smith/templates/etc/smb.conf/`` and prefixed by ``ibay-``. Eg:
+``default`` profile is located at
+``/etc/e-smith/templates/etc/smb.conf/ibay-default``.
+
+The ``default`` profile is applied if the given custom profile is not found.