HiveMind: a peer-to-peer and client-server network
Version: 0.04 Updated: November 10th 2009 9:32am EST
PART I - DESCRIPTION OF HiveMind
Section 01 - INTRODUCTION
!!!PLEASE POST ONLY REPLIES PERTINENT TO THIS TOPIC. PLEASE QUOTE THE SECTION NUMBER TO WHICH YOU ARE COMMENTING ON.!!!
This documentation will display newly added text in GREEN and will display text to be removed in RED. Previous versions of this document will be available at http://linuxfly.net/...mind/index.html
HiveMind is designed to provide peer to peer and client-server connections both between FLY operating systems (both in LiveCD and in installed and across all supported versions) and between FLY operating systems and the central HiveMind server.
HiveMind would be an opt-in authenticated service with the option for anonymous login. The basic features of HiveMind are as follows:
* GeoIP location of all users connected to the HiveMind network
* File sharing ability between users
* Multi-user file editing through an application such as Gobby
* Allows for simplifying connections to other users via VNC and/or SSH or other protocol
* Connects users to a HiveMind-only IRC channel
* Other features can be implemented
Section 02 - THE SERVER
HiveMind will have two components, a client component and a server component. The server will be run on a specific CriticalSecurity.NET server and will be used to provide authentication of HiveMind clients as well as provide a central database for GeoIP software, IRC channel, and managing connections for VNC and SSH connections between users.
The server is responsible for maintaining a database of currently connected clients. This database will include authenticated and anonymous users. The server is also going to maintain two timers for each client; a hello timer and a dead timer.
The hello timer is used to confirm a client is still connected to the server, and thus, the network. Clients will send hello packets (keep-alives) to the server at preset intervals, say 2 minutes. Everytime the server receives a hello packet, it resets the hello timer. If no hello packet is received in 7 minutes, the hello timer expires and the client is marked as dead.
Dead clients are considered disconnected from the network and any packets the server receives from a dead client are ignored. However, dead clients do not get removed from the database as soon as the hello timer expires. Once the hello timer expires, a 5-minute dead timer is started. If the server receives a packet from a dead client within the dead timer period, the server will send a re-authentication request to the client. No packets will be processed by the server until a valid authentication by the client is made. At which point, the dead timer is stopped and a 7-minute hello timer is restarted.
If no packets are received from a dead client and the dead timer expires, then that client's information is removed from the database table which keeps track of active clients.
Section 03 - THE CLIENT
The HiveMind client will be divided into two parts: the application and the daemon.
The application portion of the client will, once started, prompt the user to authenticate to the HiveMind server to connect to the network. The application will take care of the following:
* Authenticating the user to the HiveMind server (via username:password or via anonymous)
* Send keep-alive packets to the server to maintain connection
* Receiving HiveMind statistics file from the server
* Rendering the GeoIP worldmap from statistics sent from the server
* When disconnecting, sending a kill packet to the server
* When disconnecting, terminating itself
The daemon portion of the client will be responsible for the following:
* When started, will first connect to the server and check for updates to the HiveMind client application. If there are, the latest version will be downloaded.
* Run the client application
* Modify /etc/conky/conky.conf so that HiveMind statistics can be displayed in Conky
* Modify the Fluxbox menu to include the HiveMind submenu
* Modify the current Fluxbox background via 'fbsetbg' to load the worldmap with GeoIP data from connected clients
* When the application has terminated (ie disconnected and shutdown), remove the GeoIP worldmap from the background image, restore /etc/conky/conky.conf to it's pre-HiveMind state (ie: removing statistics displays) and removing the Fluxbox menu HiveMind submenu
Any user interfacing with the client will be done via the Fluxbox menu, which will consist of an entry to start the daemon (which in turn runs the application), as well as a HiveMind submenu generated when the daemon is running. The major component of the submenu will be the 'logout' entry which tells the client application to send a kill packet to the server, thus ending the connection to the network and shutting down the application, which in turn will shut down the daemon.
The daemon will have the following possible arguments:
* start = start the daemon
* stop = stop the daemon
* restart = restart the daemon, effectively, doing a stop then a start
* status = display the current running status of the daemon, ie: started or stopped
Section 04 - CONNECTION PROCESS - LOGIN
Connecting to the network does present some issues. Firstly, the loss of some degree of anonymity. When the client application is started, users will be prompted to enter their credentials. A few possibilities exist:
* Login credentials can be related to the current database of CS.net users and logging to the network would be similar to logging to CS.net This would allow certain interactions between CS and HiveMind. Users already registered on CS.net would not require to re-register. This could mean the current CS database would need some modifications.
* User accounts can be managed separately from the CS.net database and require users to register separately in order to authenticate themselves.
* Users can login by providing a username and password of their choosing without registering and this would then be used by them for the duration of their connection to the network. No database would be checked and therefor, any username:password combination would be acceptable and usable. This option can present risks.
* An option of 'guest' or anonymous login can be made if users don't have an account or don't wish to login. Certain network features could be disabled or not. Or it could be that connection to the network as anonymous is forbidden
Regardless of the method of login, a message would be presented to the user indicating the "risks" involved with connecting to the network. These "risks" would include that the user's IP and geographical location (based on IP) would be tracked by the HiveMind server, that their logging into the network would connect them to a network-only IRC channel, and that they would be condoning peer-to-peer connections to their host.
This warning message must be accepted before the user would be allowed to login (or not) and acceptance of this message and connecting to the network assumes the user is aware and accepting the "risks"
The login process would be as follows:
* The user selects the 'Start' option from the HiveMind submenu in the 'Services' category of the Fluxbox menu. Alternatively, this can also be accomplished by running /etc/init.d/HiveMind start at the command line.
* The daemon starts, does its stuff, checks for updates to the application, and then runs the application
* An xterm window of pre-defined size will open and display either ncurses of CLI.
* In either case, the first display will be a mini-EULA of sorts that informs the user of the "risks" associated with connecting to the network. If the interface is ncurses, the user must select 'yes' to continue. If the interface is CLI, the user must type in 'yes' to continue.
* If the user selects or types 'no' then the xterm window will close and this will end the process. The application will not start, and no connection to the HiveMind network or server will be made. The daemon will then shutdown.
* If the user types in a response other than 'no' or 'yes', he will be prompted that is answer was not understood and asked to type 'yes' or 'no'
* If the user selects or types 'yes' then a login prompt will be displayed. This prompt will have a field for username and a field for password. Additionally, in ncurses, a checkbox will be available for anonymous login. In CLI, a message will state that if the user wants to login anonymously, he must login using the username anonymous.
* Once login credentials are entered and 'ok' is selected, the credentials are sent to the HiveMind server for authentication.
Section 05 - CONNECTION PROCESS - CONNECTING TO THE SERVER
The first step in the HiveMind connection process would be connecting to the HiveMind server. The server side would be run on either a static IP or DNS server. When the connection is made and the user authenticated (or optionally, as anonymous), the server would record the connecting host's IP and other relevant information and add it to a database of all currently connected users.
A variant of this database would be pushed to the clients by the server during the initial connection and pushed to the clients again at regular intervals. The database would include a list of all the users logged in and connected to the server.
The client application would then list the connected logged in users via the a submenu in the Fluxbox menu. Clicking on a certain username would allow direct for a direct p2p request to that user, and if accepted, a direct p2p connection. p2p would not be available to anonymous users.
The connection to the HiveMind server will be maintained constantly while the client is connected to the network. A loss of connection to the server would be considered a loss of connection to the network.
Section 06 - CONNECTION PROCESS - MAINTAINING CONNECTION
At regular intervals, the client application will send keep-alive packets to the server so that the latter can consider that client still connected to the network and maintain an entry in the database.
This could be done via a form of keep-alive sent to the server every 2 minutes by the client. When the server receives a keep-alive from a certain client, it resets that client's hello timer. This timer could be 7 minutes long. This would allow for the client to fail to send (or the server to fail to receive) three keep-alive packets before marking a the client as dead.
The format of the keep-alive packets and ports to be used has not yet been defined.
Section 07 - CONNECTION PROCESS - DISCONNECTION
If the client fails to send (or, ultimately, if the server fails to receive) the keep-alive packets, the connection will timeout and the server will consider the client to have disconnected and it will be removed from the database.
This process can be broken down as follows:
* Every 120 seconds, the client sends a form of keep-alive packet to the server.
* When the server receives a keep-alive from a client, it resets a 7 minute hello timer.
* If the server receives no keep-alive within 7 minutes, it marks that client as dead and starts a 5 minute dead timer.
* If the server receives no packets from the dead client within 5 minutes, it deletes that client from the database.
* If the server does receive a packet from the dead client within the dead timer interval, it discards that packet and sends an authentication request to the client. If this authentication request is answered and valid, the dead timer is cancelled and a 7 minute hello timer is restarted. Any other packets or failed authentications will be dropped and will not reset or cancel the dead timer.
* If the server receives a packet from a source IP not in its database (such as a dead client when the dead timer has expired) the packet is dropped and ignored. No replies are sent to the source IP. The exception being initial authentication when HiveMind is started.
Alternatively, if the client sends a kill packet to the server, this would indicate a clean disconnection to the network and the server would remove that client from the database.
When the connection is lost to HiveMind, the client application will terminate and the client daemon will remove HiveMind-specific menu entries from the Fluxbox menu. The current StyleSwitcher theme will be reapplied, which will recover the background image, as well as return the Conky display to its default appearance, removing any HiveMind related entries, if any.
The daemon will then ensure all HiveMind processes are shut down, such as the IRC client, etc etc. Once everything is killed, the daemon itself will shut down and the Conky status window will display the HiveMind daemon as 'stopped'
Section 08 - GEOGRAPHICAL IP MAPPING
Via the use of some form of GeoIP mapping software, the HiveMind server will keep a database of all currently connected clients along with their geographical location based on the client's source IP. Geographical locations will be broken down on a per-country basis for all countries (including the USA). With the database in place, the server will compile a small file which lists countries which have connections, and the number of connections each country has.
Note: The example file is not in a specific format. The use of XML was frequently suggested to use. Please reformat as required to match the filetype used. [example file]
HiveMind GeoIP mapping [country count]
Canada = 1 United States of America = 1 England = 1 France = 1 Germany = 1 Italy = 1
[/country count] [statistics]
current connected clients = 5 most concurrent connected clients = 15 date most concurrent clients (dd/mm/yyyy) = 20/06/2010 client longest uptime = 405d 12h 23m client shortest uptime = 4m clients outdated version = 4 average client load = 0.05 0.04 0.10
[/statistics]
Countries which have no clients active will not be listed in the file. Only those that have clients will be listed. For example, if no client is GeoIP'ed as being from Canada, this would mean 'Canada = 0' However, any zero values are not added to the file, so 'Canada = 0' will not be listed in the file.
This file would be pushed to all connected client applications and processed at the client level to update a graphical map with colour coding for countries of connected clients. This map would replace the Fluxbox background image on the clients. The map would be displayed at all times when the client is connected to the HiveMind network.
This file would be pushed to all connected clients simultaneously at regular intervals, say every 10 minutes. The exception being when a client first connects to the HiveMind network (and server) it would receive the file immediately.
Due to the file format sent by the server, individual clients wont know which IPs belong to which countries, or which users are associated with which IPs. This will help maintain a certain level of privacy on the network.
The map would be generated using various shades of blue to represent users. For instance, 0 users could be blank (ie: not shade), 1 to 3 users could be a dark colour blue (say 0,0,220), 4 to 7 users could be a slightly lighter shade (say 0,0,200) etc etc etc.
When the image file is generated, the HiveMind client daemon would display this as a Fluxbox background using the command fbsetbg on the host.
Section 09 - NETWORK STATISTICS
The server can poll all connected clients in order to retrieve statistical information if desired. Such statistics can keep track of the following:
* Current number of connected clients
* Highest simultaneous connected clients
* client with the longest uptime
* client with the shorted uptime
* number of clients running out of date versions of FLY
* average load on clients
* etc etc etc
These statistics will be held in a separate table of the database and will be exported to a file along with GeoIP information and then pushed to the clients for display purposes.
Statistics sent to the clients will be displayed via Conky. This will be possible by having the client daemon modify Conky's configuration file to grep statistic outputs of the file sent by the server.
Section 10 - HiveMind IRC CHANNEL
Connecting to the network could start an IRC client and automatically connect to a specific server and channel, and authenticate the user to that server/channel. This would allow all users to communicate with each other instantly and in the same room.
As HiveMind grows, however, this may become an issue and could require splitting users into multiple rooms.
Alternatively, users could all go to the same room and then query each other for private chats in the event the main room is too crowded.
Section 11 - PEER2PEER CONNECTION
When connected, a list of peers excluding anonymous logins can be sent from the HiveMind server to the client which would list all connected clients excluding anonymous logins. If client A wishes to connect to client B, then all that would be required is to select client B from the menu. This would send a request to the HiveMind server that client A wishes direct (peer2peer) connection to client B. The server would then forward this request to client B and if client B confirms this request, the connection between A and B would be made directly.
The list of clients will be saved to a file ~/.hivemind/peers by the client application. This file will be read by the Fluxbox menu as modified by the client daemon.
A direct connection between two clients could be in the form of VNC, SSH, FTP, or other protocols.
Section 12 - PEER2PEER CONNECTION ISSUES
Due to the nature of VNC and SSH, a VNC client connecting to a VNC server must do so on an open and forwarded port. This means that FLY users would have to enable port forwarding on their routers to allow for this. This would be impractical in some situations, and impossible in others.
The benefit of the HiveMind network is that the HiveMind clients would maintain an active connection to the HiveMind server, which could be used to allow for connections to the clients without port forwarding.
Section 13 - SECURITY
Some form of secure connection should be established as part of the connection process. Be it SSL or similar. Whether the security is required or not, the option to use it should be implemented from the get-go rather than require recoding later on if we decide to use it.
This issue has been rekindled after I just read an article in the paper a few minutes ago about Canada being somewhat forced to possibly enforce new copyright laws which could ban internet subscribers as a whole (ie a household) for a year if any illegal activity (read: downloads) are detected.
As well, for certain activities such as some peer-to-peer activities, distributed computing (if implemented) or other activities would likely require some form of security.
A form of VPN was also previously suggested as an option though Im not sure if it is feasible.
Section 14 - THE FLUXBOX MENU
Features and functionality of HiveMind would be accessed via the Fluxbox menu. This menu is fully editable via the ~/.fluxbox/menu file and changes take effect immediately. Furthermore, an [include] tag in this file can link to another file to grab menu entries from it and include them without having to edit the main Fluxbox menu file. This would allow easy modification to the Fluxbox menu by adding/removing the HiveMind submenu without modifying ~/.fluxbox/menu
The HiveMind submenu would be loaded after the daemon is started and the user has connected to the network (either via username:password or anonymous) A same HiveMind submenu could be as follows:
[submenu] (HiveMind)
[submenu] (Peers)
[include] (~/.hivemind/peers)
[end]
[submenu] (Disconnect)
[exec] (Confirm) {/etc/init.d/hivemind stop}
[end]
[end]
Section 15 - DATABASES
A database will be used by the HiveMind server to store various information. At least two tables will be required: One for connected clients, and one for global statistics.
The connected clients table could have the following fields:
* Client public IP (as indicated by source IP)
* Client username (as indicated by username used to login to HiveMind)
* Client geographical location (as indicated by GeoIP or similar)
* Client uptime (as reported by command 'uptime' from client)
* Client CPU load (as reported by command 'uptime' from client)
* Client hello timer (7 minute countdown reset when server receives keep-alive packet)
* Client dead timer (15 minute countdown reset when authentication is received once hello timer has expired)
PART II - TECHNICAL ASPECTS OF HiveMind
Section 16 - RESOURCES AVAILABLE TO DEVELOPERS The following resources will be available to members of the development team:
* Hosting of files on the http://linuxfly.net server (no direct access to the server will be given. To have something hosted, contact Pilot) * Access to a Gobby collaborative text editor server (contact Pilot) * Access to the Kenai project page (contact Fallen_Demon) * FTP access to a private server can be arranged (contact Pilot) * Any other resources required, please feel free to contact either Pilot or Fallen_Demon!
Section 17 - THE DEVELOPMENT TEAM
Key team positions are as follows:
* FLY project leader: Pilot
* HiveMind project leader: Fallen_Demon
* HiveMind developers: TBD
Interested parties include:
* Thetan
* ctrlaltphreak
* vladiftodi
* Kuja
Section 18 - LANGUAGES
It has been determined the following languages will be used:
C++ for the server Python for the client
