5,838
edits
MX on Linux: Difference between revisions
m
Updated for MX release 3.15.1 - only affects section 9.4 re editing service file
m (→web sub-folder: correct link) |
m (Updated for MX release 3.15.1 - only affects section 9.4 re editing service file) |
||
| Line 320: | Line 320: | ||
==Where to install all packages?== | ==Where to install all packages?== | ||
For simplicity on this page | For simplicity on this page CHOSEN PATH (the contents of this will start with a slash “/”, but not end with a slash) is used to represent any location in the Linux file structure where you decide to install all the Cumulus packages. | ||
The phrase | The phrase “CHOSEN PATH” is used, because it is most likely you want to create the sub-folder called “/CumulusMX” (note where capital letters must be used) in a part of the Linux file structure that already exists. | ||
It is important to minimise the length of the path name, because this path name has to be passed between various different software languages (and longer paths risk truncation). | It is important to minimise the length of the path name, because this path name has to be passed between various different software languages (and longer paths risk truncation). | ||
| Line 337: | Line 337: | ||
===Creating the CumulusMX sub-folder=== | ===Creating the CumulusMX sub-folder=== | ||
* You can create sub-folder called “/CumulusMX” as you unzip a MX release, or you can type <code>sudo mkdir | * You can create sub-folder called “/CumulusMX” as you unzip a MX release, or you can type <code>sudo mkdir CHOSEN PATH/CumulusMX</code> first (note that CHOSEN PATH is explained above and always starts with a slash “/”). | ||
* By using the phrase | * By using the phrase CHOSEN PATH this advice avoids telling you to install Cumulus where you do not want it: | ||
*# Many people with a Raspberry Pi, and a little technical understanding, add an external drive to reduce wear on the internal micro-SD card, and keep their Cumulus files away from the drive that holds the operating system. | *# Many people with a Raspberry Pi, and a little technical understanding, add an external drive to reduce wear on the internal micro-SD card, and keep their Cumulus files away from the drive that holds the operating system. | ||
*#* This page is not going to get technical by telling you how to create, or mount, Linux partitions on your external drive. If your drive was bought from a Raspberry Pi reseller, they might help you. | *#* This page is not going to get technical by telling you how to create, or mount, Linux partitions on your external drive. If your drive was bought from a Raspberry Pi reseller, they might help you. | ||
*# Other people using a Raspberry Pi without that technical expertise, might use ‘’’/home/pi’’’ for | *# Other people using a Raspberry Pi without that technical expertise, might use ‘’’/home/pi’’’ for CHOSEN PATH as that is the default folder for the default user (Pi) and can be referenced as "~" in file path instructions they issue (although Cumulus will not understand that shorthand) | ||
*#* Within that ‘’’/home/pi’’’ folder, the default user has full permissions automatically. | *#* Within that ‘’’/home/pi’’’ folder, the default user has full permissions automatically. | ||
*# The developer suggests you use ‘’’/opt’’’ for | *# The developer suggests you use ‘’’/opt’’’ for CHOSEN PATH (which should be available on any Linux computer). | ||
*#* By default, the code Mark provides for installing Cumulus as a service, will run that service as a root user, and the root user has full permissions in /opt (and everywhere else) | *#* By default, the code Mark provides for installing Cumulus as a service, will run that service as a root user, and the root user has full permissions in /opt (and everywhere else) | ||
*#* (Novices: Skip this step) If you do choose a | *#* (Novices: Skip this step) If you do choose a CHOSEN PATH outside your home folder, then a more technical user can change the ownership of the "CumulusMX" sub-folder, to the default user (Pi) with <code>sudo chown -R pi: CHOSEN PATH/CumulusMX</code>, and reduce the need to use "sudo" on many actions. | ||
==Packages to install== | ==Packages to install== | ||
| Line 472: | Line 472: | ||
In a terminal session, issue commands in the following format for each file (this example relates to Raspberry Pi and uses "/var/tmp" which was defined in the extra line added to fstab earlier): | In a terminal session, issue commands in the following format for each file (this example relates to Raspberry Pi and uses "/var/tmp" which was defined in the extra line added to fstab earlier): | ||
<code>sudo ln -s /var/tmp/availabledata.json | <code>sudo ln -s /var/tmp/availabledata.json CHOSEN PATH/CumulusMX/web/availabledata.json</code> | ||
Notes: | Notes: | ||
* The "-s" flag is what says you are creating a symbolic link | * The "-s" flag is what says you are creating a symbolic link | ||
* Full paths are given both for the file that MX is to be redirected to, and after it the path where it expects to create the file | * Full paths are given both for the file that MX is to be redirected to, and after it the path where it expects to create the file | ||
* " | * "CHOSEN PATH" is defined in [[#Where to install all packages?]], but basically it starts with a "/" and defines the path to get to where "CumulusMX" is a sub-folder. | ||
* The text "availabledata.json" is just one file in the set of files linked from [[:Category:JSON Files]]. | * The text "availabledata.json" is just one file in the set of files linked from [[:Category:JSON Files]]. | ||
| Line 553: | Line 553: | ||
To run MX interactively, you must open a terminal window, and leave it open until after you have closed MX. | To run MX interactively, you must open a terminal window, and leave it open until after you have closed MX. | ||
The simplest instruction to run Cumulus MX is <code>cd | The simplest instruction to run Cumulus MX is <code>cd CHOSEN PATH/CumulusMX && sudo mono CumulusMX.exe</code>. | ||
* This is two commands issued together, the first changes the working folder, the second actually starts the main executable | * This is two commands issued together, the first changes the working folder, the second actually starts the main executable | ||
| Line 570: | Line 570: | ||
Open a terminal window, then navigate to the folder where you have installed the 3 Cumulus executables: | Open a terminal window, then navigate to the folder where you have installed the 3 Cumulus executables: | ||
<code>cd | <code>cd CHOSEN PATH/CumulusMX</code> | ||
Next decide which executable you want to run, for [[Software#Create_Missing|Create Missing utility]], that link takes you to a section of this Wiki where there are links to more information about the utility, to run it type: | Next decide which executable you want to run, for [[Software#Create_Missing|Create Missing utility]], that link takes you to a section of this Wiki where there are links to more information about the utility, to run it type: | ||
| Line 578: | Line 578: | ||
To run [[Software#Export_To_MySQL|Export To My SQL]], you change the name of the executable above and add the necessary parameters, as explained in links from that link. | To run [[Software#Export_To_MySQL|Export To My SQL]], you change the name of the executable above and add the necessary parameters, as explained in links from that link. | ||
If you have followed advice at [[#Where to install all packages?]], the user you are using will own the " | If you have followed advice at [[#Where to install all packages?]], the user you are using will own the "CHOSEN PATH/CumulusMX" folder and you may be able to omit the "sudo". | ||
Just in case it is not obvious .... if you start any executable using this command in a terminal window on your Pi, you must leave that session running, or that executable will stop running. | Just in case it is not obvious .... if you start any executable using this command in a terminal window on your Pi, you must leave that session running, or that executable will stop running. | ||
| Line 586: | Line 586: | ||
*switch off monitor or TV attached to your Pi, | *switch off monitor or TV attached to your Pi, | ||
*Just ensure you leave Pi on (with that window minimised) so that terminal session continues running. | *Just ensure you leave Pi on (with that window minimised) so that terminal session continues running. | ||
==Running MX as a Linux "systemd" service== | ==Running MX as a Linux "systemd" service== | ||
| Line 594: | Line 592: | ||
Running interactively allows MX to display error messages to you, and to confirm when it is running normally. If you run MX as a service you do not get any direct feedback, and cannot see if there has been a problem or failure. | Running interactively allows MX to display error messages to you, and to confirm when it is running normally. If you run MX as a service you do not get any direct feedback, and cannot see if there has been a problem or failure. | ||
Cumulus MX constantly develops, information here may not keep up with changes made by developer. | |||
If you are using a MX release before Patch release 3.8.4 - b3094 (14 September 2020), this "systemd" functionality was not available, and you should skip all the following sub-sections. | |||
| Line 608: | Line 610: | ||
===Defining "cumulusmx" service for "systemd"=== | ===Defining "cumulusmx" service for "systemd"=== | ||
The MX release distribution you downloaded and unzipped earlier includes a file that can be used as a starting point for the service definition. Find this file at '' | The MX release distribution you downloaded and unzipped earlier includes a file that can be used as a starting point for the service definition. Find this file at ''CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service''. | ||
For more information, see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement]. | For more information, see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement]. | ||
Please note the content of this file changes in some MX releases, the text here may not get updates each time there is such a change. The change at release 3.15.1 is described in [https://cumulus.hosiene.co.uk/viewtopic.php?p=162184#p162184 this forum post]. The text throughout this section has been updated to reflect that change. | |||
====All users - mandatory edit of service file==== | ====All users - mandatory edit of service file==== | ||
# Open the file at '' | Please note the text shown here reflects content as at release 3.15.1. If you are using an earlier, or later, release then the supplied text might be different, but the mandatory edit described here is still needed. | ||
# Open the file at ''CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor. On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor". | |||
# Within the provided file you should find a [Service] section: | # Within the provided file you should find a [Service] section: | ||
<pre>[Service] | <pre>[Service] | ||
| Line 623: | Line 629: | ||
ExecStopPost=/bin/rm /tmp/CumulusMX.exe.lock</pre> | ExecStopPost=/bin/rm /tmp/CumulusMX.exe.lock</pre> | ||
''Everyone must edit'' the line that begins with '''ExecStart=''': | |||
#* The '''mandatory''' change is to replace '''/home/install''' by what you have selected for | # There is a mandatory edit of path name, and an option to add parameters to the MX execute instruction. | ||
#* The '''mandatory''' change is to replace '''/home/install''' by what you have selected for CHOSEN PATH | |||
#* An '''optional''' change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections later, the example below assumes you want to add "-debug" | #* An '''optional''' change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections later, the example below assumes you want to add "-debug" | ||
# The new line will then read something like '''ExecStart=/usr/bin/mono-service -d: | # The new line will then read something like '''ExecStart=/usr/bin/mono-service -d:CHOSEN PATH/CumulusMX CumulusMX.exe -service -debug''' | ||
If you are a technical user, you may want to read the next few sub-sections, before you save this file and finish the edit. | |||
If you are a novice user, then you are advised to skip the technical sub-sections that follow, and proceed directly to numbered steps below that save the file and make it usable by "systemd". | |||
If you are using a standard Raspberry Pi with some types of weather station, there is a technical change mentioned for editing the "[Unit]" section of the file while you are editing it, that can be implemented to ensure that Cumulus MX does a historic data catch up if that is possible. | |||
# Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX) | # Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX) | ||
# Exit out of the editor you are using | # Exit out of the editor you are using | ||
| Line 635: | Line 649: | ||
# Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to automatically start after a reboot | # Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to automatically start after a reboot | ||
====Technical users - optional edits of service file==== | |||
Novice users should read the guidance in previous sub-section. | |||
Three sub-sections follow, the first two cover edits to different sections of the file, everyone must read the third sub-section as that describes how to end edit, and what to do next. | |||
If you already have the file open in an editor because of doing the edits in previous sub-section you are ready to skip to next sub-section. | |||
Otherwise open the file at ''CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor. On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor". | |||
=====Technical users - optional pair of edits to "[Service]" section===== | |||
Novice readers are advised to let Cumulus MX use the root user, following the suggestion below to change user/group entries may cause all sorts of problems and needs a good level of technical understanding to follow through all implications. | Novice readers are advised to let Cumulus MX use the root user, following the suggestion below to change user/group entries may cause all sorts of problems and needs a good level of technical understanding to follow through all implications. | ||
| Line 658: | Line 671: | ||
# Within the provided file you should find a [Service] section (see the contents in previous sub-section) | # Within the provided file you should find a [Service] section (see the contents in previous sub-section) | ||
# Technical users might want to edit the '''User=root''' line so that the service will run as a different user, just change the name that appears after the "=" sign. | # Technical users might want to edit the '''User=root''' line so that the service will run as a different user, just change the name that appears after the "=" sign. | ||
# Having changed the user name you may also need to edit the '''Group=root''' line to ensure the group name is valid for whatever new user you selected. | |||
=====Technical users - optional edit to "[Unit]" section===== | |||
The content of the "[Unit]" section of the service description file described here has evolved as MX develops. The main change is in references to '''network-online.target''': | |||
* It did not appear at all in Patch release 3.8.4 - b3094 (14 September 2020) | |||
* It appeared as <code>After=network-online.target</code> at some later release. | |||
* From release 3.15.1 build 3170 (19 March 2022) it appears twice | |||
<pre>Wants=network-online.target | |||
After=network-online.target</pre> | |||
# Within the provided file you should find a '''[Unit]''' section: | |||
#* As mentioned above, the content of this section depends upon which MX release you are using. | |||
#* All release distributions that contain the file should have the following three lines: | |||
#*# <code>[Unit]</code> | |||
#*# <code>Description=CumulusMX service</code> | |||
#*# <code>Documentation=https://cumuluswiki.org/a/Main_Page</code> | |||
#* What follows after that depends on which release distribution you have installed | |||
#** You may see a line saying <code>After=network-online.target</code>, that means that if the network online detection service has been started, and the network service is not running, then "systemd" should ensure that the network service is started after the "cumulusmx" service i.e. it requests starting a connection by LAN or Wireless to the internet after starting MX. | |||
#** You may see a line saying <code>Wants=network-online.target</code>, that tells "systemd" that the "cumulusmx" service wants the network online detection service to be started. Note that the terminology ''wants'' means MX can still start even if the network service is not running, or if the attempt to start the network service fails | |||
# Technical users should use the editor to create a blank line after <code>Documentation=https://cumuluswiki.org/a/Main_Page</code> | |||
# Type into that blank line the following: <code>Requires= time-sync.target local-fs.target</code> | |||
#* The terminology ''Requires'' tells "systemd" that the "cumulusmx" service should not be started until the services specified on that line have successfully started | |||
#*# The '''local-fs.target''' specifies that the ''cumulusmx'' service requires the file service to have started, i.e. checks your computer can read files before it attempts to start the ''cumulusmx'' service | |||
#*# The '''time-sync.target''' specifies that the ''cumulusmx'' service requires the computer to have synced with either a real-time clock chip, or a time found on the internet (NTP), i.e. this will ensure that Cumulus obtains the correct time from the computer to control all its actions | |||
#*#* If you are using a weather station type that does not time-stamp the reading it supplies to a Raspberry Pi, adding that target reference is important | |||
#*#* A standard RPi does not include a real time clock chip (it can be added via connections available), therefore when the RPi boots it initially uses a dummy clock, and this sets the time to when the RPi was last running. | |||
#*#* That means without this target being included, a newly booted-up RPi will tell Cumulus MX the time is just after when the computer was shut down, that might be very different to the true current time. It means your Cumulus MX on restarting will skip the catch-up of historic data (should your weather station settings make that available). Some measurements will then get logged against the wrong time. | |||
#*#* When the Raspberry Pi does do a time-sync, the time will suddenly jump, this is serious if this means the "rollover" time has been skipped over, as it implies the "dayfile.txt" will miss a line, and many measurements will be logged to wrong day. | |||
=====Technical users - Saving the file and making it available to "systemd"===== | |||
# Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX) | # Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX) | ||
# Exit out of the editor you are using | # Exit out of the editor you are using | ||
| Line 664: | Line 711: | ||
# Now type <code>sudo systemctl daemon-reload</code>, this tells "sytemd" that it needs to reload all service definitions because either one has changed, or a new one has been added | # Now type <code>sudo systemctl daemon-reload</code>, this tells "sytemd" that it needs to reload all service definitions because either one has changed, or a new one has been added | ||
# Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to automatically start after a reboot | # Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to automatically start after a reboot | ||
== Optional parameters to add to the instruction to run the MX engine == | == Optional parameters to add to the instruction to run the MX engine == | ||
| Line 721: | Line 767: | ||
==== -wsport parameter for web sockets ==== | ==== -wsport parameter for web sockets ==== | ||
Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono | Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono CHOSEN PATH/CumulusMX/CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''. | ||
Note use of this parameter is now deprecated, as it has been incorporated into '''-port''' parameter described earlier. The reason is that [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]]. | Note use of this parameter is now deprecated, as it has been incorporated into '''-port''' parameter described earlier. The reason is that [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]]. | ||