Devel manual: pull readme updates

developer-manual/en/nethserver-dc.rst

@@ -1,12 +1,19 @@
 nethserver-dc
 =============
 
-The nethserver-dc package runs a systemd-nspawn container with a vanilla Samba 4.3.4 inside of it. It downloads, installs, configures and provision an Active Directory domain controller based on Samba.
+The nethserver-dc package runs a systemd-nspawn container (``nsdc``) with a vanilla
+Samba 4 inside of it. It downloads, installs, configures and provision an Active
+Directory domain controller based on Samba.
 
-Samba machine needs an IP address in a green network, different from the machine one. It also requires a bridge on the green interface. If needed, this bridge is created automatically. ::
+The ``nsdc`` container needs an IP address in a green network, different from the
+host machine one. It enslaves its network interface to a host bridge, with green
+role. If needed, this bridge is created automatically. 
+
+This is a typical configuration::
 
   # config show nsdc
   nsdc=service
+     ProvisionType=newdomain
      IpAddress=192.168.122.50
      bridge=br0
      status=enabled
@@ -15,25 +22,32 @@ nethserver-dc-save event
 ------------------------
 
 * it creates and configures systemd-nspawn machine (nethserver-dc-install
-  action). Machine is provisioned with domain and realm taken from local system
-  and won't be possible to change them anymore. For instance if system domain is
-  `nethserver.org` domain will be `NETHSERVER` and realm `nethserver.org`. Those
-  parameters are read from
-  `/var/lib/machines/nsdc/etc/sysconfig/samba-provision` template. To have a
-  shell inside nspawn machine, you can use ::
+  action). The Samba domain is provisioned by the ``samba-provision.service`` unit, according 
+  to the ``ProvisionType`` prop value. Supported values are:
+
+  - ``newdomain`` (default): domain and realm are taken from local system and
+    won't be possible to change them anymore. For instance if system domain is
+    `nethserver.org` domain will be `NETHSERVER` and realm `nethserver.org`.
 
-  # systemd-run -M nsdc -t /bin/bash
+  - ``ns6upgrade``: connect the LDAP service running on the host machine and 
+    migrate the WS/PDC domain from ns6 backup to an Active Directory domain.
+    The realm and domain name are set as described in the ``newdomain`` provision 
+    type.
 
 * it creates a network bridge if needed, or select an existing one and save it in nsdc bridge db prop (`nethserver-dc-create-bridge` action)
 
 * it waits for the machine to come up (`nethserver-dc-waitstart`)
 
-* it joins the domain of new machine using default credentials (`nethserver-dc-join`). To join domain manually, clear sssd.conf, join domain and expand sssd.conf template
+* it joins the domain of new machine using default credentials (`nethserver-dc-join`).
 
 * it sets the password policy (`nethserver-dc-password-policy`)
 
 Realmd writes a lot of information on the system journal. See `journalctl` command. 
 
+To have a shell inside the ``nsdc`` container, you can run ::
+
+ # systemd-run -M nsdc -t /bin/bash
+
 
 Manual Join
 -----------
@@ -45,18 +59,18 @@ nethserver-dc-join action joins automatically to domain. If you want to join dom
 
 then clear sssd.conf, join domain and expand sssd.conf template ::
 
-   # > /etc/sssd/sssd.conf
-   # realm join `config get DomainName`
-   # expand-template /etc/sssd/sssd.conf
+   > /etc/sssd/sssd.conf
+   realm join $(hostname -d)
+   expand-template /etc/sssd/sssd.conf
 
 Then provide the default administrator password::
 
    Nethesis,1234
 
 If everything goes well ::
 
-   # getent passwd administrator@`config get DomainName`
-   administrator@nethserver.org:*:261600500:261600513:Administrator:/home/administrator@nethserver.org:/bin/bash   
+   getent passwd administrator@$(hostname -d)
+   # output: administrator@nethserver.org:*:261600500:261600513:Administrator:/home/administrator@nethserver.org:/bin/bash   
 
 Once domain is joined, you can manage users from interface. From command line, you can use `net` command ::
 
@@ -65,22 +79,28 @@ Once domain is joined, you can manage users from interface. From command line, y
 Factory reset
 -------------
 
-The "Start DC" procedure from the UI is designed for a single run.  If it fails,
-reinstalling the whole server can be avoided with some bash commands.
+The "Start DC" procedure from the "Accounts provider" page is designed for a
+single run.  If it fails, reinstalling the whole server can be avoided by
+running the following command ::
 
-The following steps are required to clean up the DC state and prepare it for a
-new provisioning run. ::
+    signal-event nethserver-dc-factory-reset
 
-    realm leave
-    systemctl stop nsdc sssd
-    systemctl disable nsdc sssd
-    rm -vf /var/lib/machines/nsdc/etc/samba/smb.conf
-    find /var/lib/machines/nsdc/var/lib/samba/ -type f | xargs -- rm -vf
-    config setprop sssd Provider none status disabled AdDns ''
-    > /etc/sssd/sssd.conf
-    signal-event nethserver-dnsmasq-save
-    config setprop nsdc status disabled IpAddress ''
+The command cleans up the DC state and prepare it for new provisioning run.
+**Any existing user and group account is erased**.
+
+If a full DC reinstall is desired, after factory reset event, run also ::
+
+    rm -rf /var/lib/machines/nsdc
+
+Uninstall nethserver-dc
+-----------------------
+
+* Run the DC factory reset procedure and remove the :file:`/var/lib/machines/nsdc`
+  directory.
+
+* Uninstall the package ::
 
+    yum remove nethserver-dc
 
 Changing the IP address of DC
 -----------------------------

developer-manual/en/nethserver-directory.rst

@@ -152,3 +152,24 @@ If output appears to be base64-encoded type: ::
   ldapsearch -LLL -Y EXTERNAL -b cn=config -s one 'objectClass=olcDatabaseConfig' olcAccess 2>/dev/null | perl -MMIME::Base64 -MEncode=decode -n -00 -e 's/\n +//g;s/(?<=:: )(\S+)/decode("UTF-8",decode_base64($1))/eg;print'
 
 
+Upgrade to Active Directory
+===========================
+
+If the LDAP database has been restored from a ns6 backup set, it is possible
+to upgrade it to a local Active Directory accounts provider.
+
+A ns7 LDAP database cannot be upgraded to Active Directory. It lacks the Samba
+LDAP schema extensions required by the Samba *classic upgrade* procedure.
+
+The ``nethserver-directory-ns6upgrade`` event 
+
+- removes the ``nethserver-directory`` RPM
+- installs and configures ``nethserver-dc``
+
+Before running the event, assign a free IP address to the ``nsdc`` Linux
+container, installed by ``nethserver-dc`` RPM. Ensure it is **a free IP
+address** of a **green network**.
+
+    config set nsdc '' IpAddress A.B.C.D
+    signal-event nethserver-directory-ns6upgrade
+

developer-manual/en/nethserver-firewall-base.rst

@@ -294,7 +294,7 @@ A configured network interface is automatically a zone.
 A service can have a protocol and one or more ports. A ``service`` entry in ``fwservices`` database can be something like: ::
 
     name=fwservice
-       Protocol=TCP/UDP/TCPUDP/ICMP
+       Protocol=tcp/udp/tcpudp/icmp
        Ports=port/port range
 
 A service can also be a refence in the format ``ndpi;<protocol>`` where ``protocol`` is a supported protocol from nDPI kernel module.

developer-manual/en/nethserver-virtualhosts.rst

@@ -19,6 +19,30 @@ A new ``vhost`` database is defined by this module. It contains records of type
         SslCertificate=/etc/pki/tls/certs/NSRV.crt
         status=enabled
 
+The database contains a special ``default`` record which represents the defaul virtual host: ::
+
+  default=vhost
+    Description=Default virtual host
+    FtpPassword=
+    FtpStatus=enabled
+
+This virtual host is always enabled and can't be deleted.
+If FTP access is enabled, the user will be chrooted inside ``/var/www/html`` directory.
+
+NethServer 6 upgrade
+--------------------
+
+Shared folders from NethServer 6 with property ``HttpStatus`` set to ``enabled`` can
+be migrated to virtual hosts using the ``vhost-migrate-ibay`` event: ::
+
+    signal-event vhost-migrate-ibay <ibay-name>
+
+If the original ibay was availble to any virtual hosts (`HttpVirtualHost` = ``__ANY__``),
+the ibay will be migrated inside the ``default`` virtual host.
+Otherwise a new virtual host record will be created.
+
+The migration process is also available from the web interface.
+
 UI plugins
 ----------
 
@@ -27,4 +51,4 @@ controller and the respective template under ``ModifyPlugin/`` directories.
 
 See the `Samba User plugin`_ on NethServer 6.x as an example
 
-.. _`Samba User plugin`: https://github.com/NethServer/nethserver-samba/blob/9012fbcd0cb3db60d8fb0ddfcd3db9e39a01956c/root/usr/share/nethesis/NethServer/Module/User/Plugin/Samba.php
+.. _`Samba User plugin`: https://github.com/NethServer/nethserver-samba/blob/9012fbcd0cb3db60d8fb0ddfcd3db9e39a01956c/root/usr/share/nethesis/NethServer/Module/User/Plugin/Samba.php