Merge pull request #10 from kc0euw/docContrib

Add content for Email and File Sharing sections

arednGettingStarted/advanced_config.rst

@@ -81,7 +81,7 @@ VLAN 2
 No VLAN tag
   Packets received by the node that are untagged will be identified as LAN traffic from computers on the local area network.
 
-It is important to understand AREDN |trade| VLANs when configuring network smart switches for Internet access, tunneling, or DtD linking of nodes. There are some useful tutorials available on the AREDN |trade| website for configuring VLAN-capable switches: `Video <https://www.arednmesh.org/content/understanding-vlans>`_ or `Text+Images <https://www.arednmesh.org/content/configuring-netgear-gs105e-switch-lanwan-ports>`_.
+It is important to understand AREDN |trade| VLANs when configuring network smart switches for Internet access, tunneling, or DtD linking of nodes. There are some useful tutorials available on the AREDN |trade| website for configuring VLAN-capable switches: `Video <https://www.arednmesh.org/content/understanding-vlans>`_ or `Text+Images <https://www.arednmesh.org/content/configuring-netgear-gs105e-switch-lanwan-ports>`_. Also, on the AREDN |trade| GitHub site there is more information about node VLANs that have been preconfigured in the firmware images for specific types of radio hardware. For additional information visit this link: `Ethernet Port Usage <https://github.com/aredn/aredn_ar71xx#ethernet-port-usage>`_
 
 Port Forwarding, DHCP, and Services
 -----------------------------------

arednServicesGuide/chat_programs.rst

@@ -2,9 +2,9 @@
 Chat Programs
 =============
 
-`Online chat <https://en.wikipedia.org/wiki/Online_chat>`_ programs include any application which transmits short text messages between the sender and receiver. These realtime keyboard-to-keyboard messages create an environment similar to a spoken conversation. A chat session may involve one-to-one communication or group meetings. These programs are valuable for quick question/answer interactions where immediate replies are important. Timestamped conversation history is typically saved for future reference.
+`Online chat <https://en.wikipedia.org/wiki/Online_chat>`_ software includes any program which transmits short text messages between the sender and receiver. These realtime keyboard-to-keyboard messages create an environment similar to a spoken conversation. A chat session may involve one-to-one communication or group meetings. These programs are valuable for quick question/answer interactions where immediate replies are important. Timestamped conversation history is typically saved for future reference.
 
-Chat programs are one of the least network-intensive types of communication programs, so they are a good candidate as low impact services on a mesh network. Many chat programs also offer file sharing, which allows you to get two functions within a single program. The following list of applications is not comprehensive or complete, but represents a sample of the types of chat programs that might be available for you to use as services on your mesh network. Only programs with open source licenses were included in this list, although there are commercial chat applications that can also be used.
+Chat programs are one of the least network-intensive types of communication programs, so they are a good candidate as low impact services on a mesh network. Many chat programs also offer file sharing, which allows you to get two functions within a single program. The following list is not comprehensive or complete but represents a sample of the types of chat programs that might be available for you to use as services on your mesh network. Only programs with open source licenses were included in this list, although commercial chat software can also be used.
 
 MeshChat
 --------

arednServicesGuide/collaborative_editing.rst → arednServicesGuide/dispatch_programs.rst

@@ -1,6 +1,6 @@
-==============================
-Collaborative Document Editing
-==============================
+================================
+Computer Aided Dispatch Programs
+================================
 
 .. important:: This section of the documentation is currently a work in progress.
 

arednServicesGuide/email_programs.rst

@@ -2,9 +2,73 @@
 Email Programs
 ==============
 
-.. important:: This section of the documentation is currently a work in progress.
+`Email <https://en.wikipedia.org/wiki/Email>`_ programs have become a communication standard for workers everywhere today. Email messages can include a wide range of information, from short chat-like interactions to lengthy and extensive text with complex document and image attachments. Whereas chat programs often assume that the sender and receiver are online at the same time, email programs use a `store and forward <https://en.wikipedia.org/wiki/Store_and_forward>`_ approach to ensure message delivery even when users are not connected simultaneously.
 
+Email operates on a client-server model. Users create or read their messages on some type of client program, although this software could be hosted on a network web server and accessed through a user's web browser rather than requiring a standalone email program to be installed on the client computer. Client programs typically access messages from the email server using either `Internet Message Access Protocol (IMAP) <https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol>`_ or `Post Office Protocol (POP) <https://en.wikipedia.org/wiki/Post_Office_Protocol>`_. Client programs use `Simple Mail Transfer Protocol (SMTP) <https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol>`_ to send messages to email servers, while the servers themselves use SMTP for both sending and receiving.
 
+As with any client-server program, the email server must be reachable on a network segment with adequate bandwidth in order for the clients to exchange messages. If you have a choice, put your email server on one of your largest and most reliable network segments. Refer to this link for a comparison of email `Client Programs <https://en.wikipedia.org/wiki/Comparison_of_email_clients>`_, and visit this link for a comparison of email `Server Programs <https://en.wikipedia.org/wiki/Comparison_of_mail_servers>`_. The following list is not comprehensive or complete but represents a sample of the types of software that may be available for you to use as services on your mesh network. Only programs with open source licenses were included in this list, although commercial email software can also be used.
+
+Citadel/UX
+----------
+
+Not only does Citadel provide email, but it is also a full-featured *groupware* suite with chat rooms, calendars and scheduling, contact address book, file sharing, forum posting, and many other features. It contains built-in implementations of the following server protocols: IMAP, POP3, SMTP, XMPP, and ManageSieve. Citadel also provides user self-registration, which minimizes the administrative overhead of managing email addresses on the server.
+
+Since a variety of features are bundled into a single application suite, Citadel is a less complicated and more integrated way to implement several network services at once by installing a single package capable of running on a lightweight `Raspberry Pi <https://en.wikipedia.org/wiki/Raspberry_Pi>`_ computer if necessary. Citadel's email services can be accessed using its browser-based webmail interface or from a separate email client program on a remote computer. For additional information about Citadel, visit this link: `Citadel <https://en.wikipedia.org/wiki/Citadel/UX>`_
+
+Open Source Email Server
+------------------------
+
+In order to implement an open source email server you will probably need to install several individual software packages, each of which will process one or more of the required email protocols. This is slightly more complicated than implementing a single groupware package such as the *Citadel* program described in the previous section. Protocols and example packages are described in the following lists.
+
+**SMTP**
+  In order to implement an email server you will need to select a software package to handle the Simple Mail Transfer Protocol. You can select one of the example open source packages from the list below, or you can implement another SMTP agent of your choice.
+
+  * `Sendmail <https://en.wikipedia.org/wiki/Sendmail>`_ is the original legacy SMTP server that is still used today, although one of the newer programs below is often chosen for its ease of configuration and added security features.
+  * `Exim <https://en.wikipedia.org/wiki/Exim>`_ is the default SMTP server in Debian Linux, is well-documented, having many configurable features, and it runs from a single executable program.
+  * `Postfix <https://en.wikipedia.org/wiki/Postfix_(software)>`_ is the default SMTP server in Ubuntu Linux and MacOS, with many integration and security features, and it runs a series of parallelized programs for improved performance.
+
+**IMAP and POP3**
+  In order for email clients to retrieve their messages you will need to select a software package to handle IMAP and POP3 communication. You can select the example open source package below or you can implement another IMAP/POP3 package of your choice.
+
+  * `Dovecot <https://en.wikipedia.org/wiki/Dovecot_(software)>`_ is one of the most popular IMAP and POP3 servers for open source email systems, being found on more than 2/3 of the email servers across the Internet.
+
+You will need to have detailed knowledge and skills when building your own open source email server, with the advantage of having complete control over everything on the system. There is some administrative overhead for creating and maintaining all user email accounts, as well as handling other management tasks on your system. Using these open source software packages, it is possible to build a very robust email server that is capable of running on a small portable computer like a `Raspberry Pi <https://en.wikipedia.org/wiki/Raspberry_Pi>`_.
+
+Using WinLink to Send Email
+---------------------------
+
+Although it is not typically used as a TCP/IP network application, many operators are already familiar with `WinLink 2000 <https://en.wikipedia.org/wiki/Winlink>`_ for sending message traffic between WinLink computers across amateur radio frequencies. It is possible to configure *RMS Express* and Telnet Post Office or Telnet P2P for sending email with attachments across a mesh network. You will need a stable Microsoft Windows computer with plenty of memory to run this system (8GB recommended). Refer to the information link below for details about the specific network port settings that will be required. The maximum attachment size is currently 5MB per message as compared to the 100KB limitation on HF and Packet RMS stations. For additional information, please visit the AREDN |trade| forum category on Winlink located here: `Winlink Forum <https://www.arednmesh.org/forums/winlink>`_
+
+
+Keeping Multiple Servers in Sync
+--------------------------------
+
+Since the email *server* must be reachable on the network in order for *clients* to send and receive messages, and since a solitary email server can be a single point of failure, it may be useful to explore ways for redundant email servers to be kept in sync across the network. If one email server becomes unreachable, a backup or failover server could be used to keep the email service running.
+
+For mission-critical services on high speed data networks, *Disaster Recovery* designs are often implemented to ensure that services continue operating in the event of a failure. There are several methods for accomplishing this, which usually involve duplicating server hardware and software with some type of data replication between these systems. At a high level, two basic designs could be implemented as described below.
+
+**Manual Failover Design**
+  In this design there is a primary server that remains active, with a duplicate backup server located on another network segment. The standby server is brought online only if the primary server becomes unreachable. Data that contains the configuration and message history on the primary server could be copied periodically to the standby server using an intelligent utility such as `rsync <https://en.wikipedia.org/wiki/Rsync>`_ running as a scheduled task which copies only what has changed since the last check. This design provides a fallback that can be used in case of emergency, but it requires some degree of manual intervention to bring up the standby service on the network when the primary becomes unreachable.
+
+**Automated Failover Design**
+  `High Availability <https://en.wikipedia.org/wiki/High-availability_cluster>`_ technology allows two or more sets of computing resources to send `heartbeat <https://en.wikipedia.org/wiki/Heartbeat_(computing)>`_ signals for detecting whether their services are available across the network. Several types of open source and commercial clustering packages are available, which provide varying degrees of complexity and recovery capabilities. Suffice it to say that many options are available for ensuring the availability of mission-critical services on your network. Feel free to research, investigate, and test several of these options if you have a pressing need for highly available mesh services.
+
+As a general rule for mesh networks, simpler is better. The more complicated and automated you make your service design, the more network and computing resources will be required to operate the system. It is always best to conserve mesh networking resources wherever possible.
+
+
+Example Email Service Comparison
+--------------------------------
+
+Platform abbreviations:
+  win=MS Windows, mac=Apple, lin=Linux, rpi=Raspberry Pi
+
+==========  ==================  ============  ===============  ======
+Program     Features            Network Load  Platform         Effort
+==========  ==================  ============  ===============  ======
+Citadel     groupware, webmail  small         lin/mac/rpi      easy
+Open Email  client-server       medium        lin/mac/rpi      expert
+WinLink     email, attachments  small         windows          medium
+==========  ==================  ============  ===============  ======
 
 .. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
    :ltrim:

arednServicesGuide/file_sharing.rst

@@ -2,9 +2,36 @@
 File Sharing Programs
 =====================
 
-.. important:: This section of the documentation is currently a work in progress.
+`File sharing <https://en.wikipedia.org/wiki/File_sharing>`_ is a method of providing network users with access to digital content. One way to accomplish this is to *push* a copy of a file to users' computers, using either an email attachment or a file transfer program. Another approach is to create a central repository and allow users to *pull* files from this file share. Unless there is a special reason for pushing content, it is usually preferable to let users pull content as needed.
 
+File transfer protocols themselves have minimal impact to network performance, but downloading a very large file across a mesh network could have a major performance impact. Transferring text files, and especially compressed text, should have minimal impact to the network, but a network could experience performance degradation while transferring files with lots of embedded formatting directives or images. High resolution audio files, image captures, or video recordings will also tax network resources when they are moving between nodes.
 
+The following list is not comprehensive or complete but represents a sample of the types of programs that might be available to use for file sharing on your mesh network. Only programs with open source licenses were included in this list, although commercial software can also be used.
+
+FTP Services
+------------
+
+`File Transfer Protocol (FTP) <https://en.wikipedia.org/wiki/File_Transfer_Protocol>`_ servers can be configured as file repositories from which users can copy digital content using FTP client programs. Some of the more common FTP server packages include `FileZilla Server <https://en.wikipedia.org/wiki/FileZilla#FileZilla_Server>`_, `ProFTPD <https://en.wikipedia.org/wiki/ProFTPD>`_, `Pure-FTPd <https://en.wikipedia.org/wiki/Pure-FTPd>`_, and `vsftpd <https://en.wikipedia.org/wiki/Vsftpd>`_ (which is the default FTP server in many Linux distributions).
+
+All of the most common web browsers allow content to be downloaded using FTP, although they may not support all protocol extensions. However, there are many `FTP client programs <https://en.wikipedia.org/wiki/Comparison_of_FTP_client_software>`_ with complete FTP support. FTP is a tried-and-true method for retrieving files from a central repository.
+
+Web Services
+------------
+
+File sharing can be accomplished by hosting downloadable files on a web server. These files can be downloaded from within web browsers using `Hypertext Transfer Protocol (HTTP) <https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol>`_ as well as other built-in file transfer protocols. Simply place files to be shared into the website directory structure and provide links to them on web pages.
+
+There are also many web service packages that provide a robust file sharing interface similar to online cloud storage solutions. One example is `NextCloud <https://en.wikipedia.org/wiki/Nextcloud>`_, an open source file hosting suite with features similar to many of the Internet-based `cloud storage services <https://en.wikipedia.org/wiki/Comparison_of_file_hosting_services>`_.
+
+Users login to NextCloud to see available content, and file sharing permissions can be set on a user or group basis. Files and folders can be uploaded, downloaded, moved, renamed, deleted, and previewed (depending on file type). Simple file version control is provided through auto-backup, and the *Details* sidebar lists past versions available for rollback. These and other similar software packages can provide a full-featured file sharing service when hosted on a web server.
+
+Collaborative Computing
+-----------------------
+
+Collaborative computing enables people to collaborate on documents together in real time. Multiple users dispersed across a wide geographic area can be working simultaneously to create or modify a set of documents that are available to others over the network. With this type of collaborative model, documents no longer need be viewed as static but can become truly living projects.
+
+One example package that facilitates collaborative document creation is `Etherpad Lite <https://en.wikipedia.org/wiki/Etherpad>`_. Users access the Etherpad server through a web browser, so no client software is required on the users' computers. Anyone who connects to the service can create a new document or contribute to an existing document. Active users are displayed and have the ability to chat with each other in the messaging area. Changes to a document are periodically auto-saved, but users can force a checkpoint to capture the current state of a document. The "time slider" control allows users to view document revisions at any point in time throughout its history. Documents can be downloaded in several formats (text, HTML, Open Document, Microsoft Word, or PDF).
+
+`Collaborative document sharing <https://en.wikipedia.org/wiki/Document_collaboration>`_ could be very helpful for a number of EmComm use cases, such as maintaining an accurate picture of deployed resources at various locations during an incident or event. Document version tracking makes it possible to scroll back and forth in history to see the status of deployed resources at any given time, as well as to capture information and save it for wider distribution.
 
 
 .. |trade|  unicode:: U+02122 .. TRADE MARK SIGN