Home > Documentation > MCPae

MCPae for Janmesh - Documentation

MCPae - Introduction

MCPae is a PHP (no db) web application meant to run over a cjdns virtual, secure network. It is not intended to be used on an Internet server since it relies entirely on cjdns to provide security and privacy.
It is developed as a part of the Janmesh project, a citizen-to-citizen networking initiative providing help to set up an alternative communication mean, resistant to severly disruptive conditions.

The Janmesh project focuses on neighbour-to-neighbour links (a.k.a Joint Access Mesh Networking) using a CoOoOw network stack (cjdns over olsrd over open wifi).
To learn more about all this, and before continuing to read about MCPae, please refer to the root of this site, http://janmesh.net to make sure you will understand what is all this about.
MCPae provides a general frame for any purpose when used alongside a cjdns network. It is coded as a part of the Janmesh project, but besides meshlocals it can also be useful at the world scale such as an example with the Hyperboria global cjdns-powered network.
It is typically installed on a dedicated computing device ("meshbox") that is not too greedy for electric power and can be kept online 24 hours a day

This is a web application, running on a web server, and therefore the services provided can be accessed, once the meshbox is plugged in into your home LAN router/access point, from any device of your household that features a web browser.
The core of MCPae is the Store, that can be used to distribute/install MCPae modules that add features to the main software.

Possible application could include file sharing, messaging, video calls, chatrooms, microblogging, social networking, online shops, music distribution, to mention just a few.

How to install MCPae on your Janmesh device

...For now MCPae is still in early stage. It is therefore not currently available for download.
Currently, only the setup wizard is ready to use. This means you cannot do anything useful with the software.
What is planned is to add the "user account creation/deletion" feature first. Then, to add the necessary architecture (an API to work with) for modules to interact, with MCPae, with the user, with other instances of MCPae available on the Janmesh network, and with other modules installed on the same instance.
Then, to allow users to change settings (typically, change their password). And finally, to add at the admin level a module store ("the Store") which would allow to publish a module, to download a module from a specified Store, to republish a module downloaded before, to blacklist or uninstall modules.

System requirements

PHP >= 7.0
"Zip" php extension (often build-in in most distribution packages of PHP)

How to use the setup wizard for MCPae installation

Important notice Make sure to turn off Janmesh during the installation process to prevent for sure any confidential data leak. # /etc/init.d/janmesh stop
# nmcli conn down janmesh

Cloning MCPae from git
Once logged in into your Janmesh box you'll have to:
$ git clone <Address not available for now, please check back in some dozens of weeks> Create, as root, a subdirectory in your public www dir, which would be typically something like # mkdir /var/www/html/mountpoint This directory will be refered as the mountpoint ; you can run several instances of MCPae on different mountpoints using the same HTTP server.
Copy the MCPae code there. # cp -R mcpae-janmesh/www-root/* /var/www/html/mountpoint

Change the owner of the mountpoint directory to www-data with the command chown -R
Check with your web browser the address http://localhost/(mountpoint)
If you see a fatal error message indicating that some directories that have to be private are reachable from the outside, it means that your HTTP server don't apply the .htaccess directives. You'll have to tweak your http server configuration according to your own setup (in most case by editing the configuration file to "AllowOveride All".


You should see a message indcating that you have to edit a file to indicate your admin credentials
note: If you forget your admin credentials, you'll have to erase pwd.dat in the data/admin directory, and to restore (re-copy) the original admin_credentials.php, then to edit it accordingly to set a new password.

edit-as root- the file (www_root)/(mountpoint)/data/admin/admin_credentials.php to set up your admin login and password.
# nano (www_root)/(mountpoint)/data/admin/admin_credentials.php
...To set up the administrator login and password for your instance.

next step will be to log in with the credential you just entered. The setup wizard will then ask you to indicate the IPv6 address of your tun0 interface. you can get it using the command
$ ifconfig

How to block anything and allow only the port used by MCPae

You may want to use only services provided by MCPae -but beware, any other web application served by your HTTP server will remain accessible through the mesh.
If you want to allow a listening web server (port 80) and block anything else, for a mesh network operating on the tun0 interface: as root:
# ufw deny in on tun0
# ufw allow in on tun0 to any port 80

The basics of MCPae concepts: the addresses

The smallest unit for the purpose of running MCPae is the instance identifier built out of the IPv6 address of the instance followed by a double slash folowed by the mountpoint.
Example:
1234:5678:91ab:cdef:fedc:ba19:8765:4321//mymountpoint
It is mostly useful only for inter-instance communications

MCPae communications

All MCPae's components and module communication is handled trough HTTP APIs.

Inter instances communications

These, are connections etablished by the core MCPae software between distincts MCPae instances. They are using cjnds network and the MCPae addresses as defined above. It is donne by opening an HTTP connexion at the url with two to three GET parameters : -A meta parameter specifiying that the nature of the message is inter-instances communication -An action parameter specifiying which command as to be executed by the API -An array of optional arguments Typical usages: ping, handshake...

Communication between MCPae and its modules

Render module's graphical UI

Communication between local modules

Communication between distant modules

The Store addresses

Any MCPae instance has the ability to let publish new modules that extends MCPae functionnalities.

The Store operates at administrator level, and only the administrator of an instance can install, uninstall, or activate/deactivate modules.

One of the first things you may want to do with a newly installed MCPae instance is to reach a Store to install new modules.

For this you will need to know its address, which is of the form:
store://1234:5678:91ab:cdef:fedc:ba19:8765:4321//mymountpoint
Once a Store is added to your store list, you can browse module distributed there and install some of them.

The User addresses

Administrator account and user accounts are separated entities. Users, as an example for Message purpose, are identified by an user ID.
The User ID can only include the following characters :
a-z
A-Z
0-9
.
-
_
 The address (as an exemple, Message address) that is to be used when an user needs to be designated, is of the form:
userID#1234:5678:91ab:cdef:fedc:ba19:8765:4321//mymountpoint

Modular architecture

Common methods to be implemented to create a module

The MCPae API available for module developers

Communication between MCPae front-end and a module

Communication between modules on the same instance

Communication between distant instances modules

Licensing: this tutorial is placed under two licenses. Code is placed under AGPLv3 license. Other text content here is licensed under Creative Commons BY-SA 4.0 license. Authors are : Shangri-l. Translators are : Nomys. Translation proofreader are : Shangri-l