mqtt.ideate.cmu.edu

• Registered ports
• Student guide: Client/enduser usage
• Instructor guide: Instance/port management

Registered ports

Separate mqtt server instances have been set up for courses that have requested them; each is allocated its own port. IDeATe instructors interested in an instance/port being allocated to their course should email help@ideate.cmu.edu. All access control within a course instance is managed by its instructor(s).

Port assignments are as follows:

Students enrolled in these courses should contact their instructor(s) for the appropriate credentials with which to connect their devices.

Student guide: Client/enduser usage

1. Find your device's MAC address.
   • Your instructor(s) should have more detailed guidance on how best to find the MAC address of the specific devices you will be using in class.
2. Register your device to the CMU-DEVICE network at https://getonline.cmu.edu/hosts/register/wireless/.
   • Do NOT connect IoT devices to the CMU-SECURE network, as this would require storing your Andrew credentials on the device, which violates Andrew password management guidelines.
   • Note that, per university networking policy, registrations to the CMU-DEVICE network are subject to being purged upon separation from the university or after several months of inactivity on the network. You should receive an email notice before this occurs.

2. Connection configuration

Your instructor(s) should have more detailed guidance on how best to configure the specific devices, frameworks, and tools you will be using in class.

1. Obtain the mqtt credentials (username and password) for your class, team, or group from your instructor(s).
   • Depending on the curricular goals of your course, you may be given separate sets of credentials for different types of devices, e.g., those classified as "listeners" versus "controllers". If so, be sure to use the correct credentials for each device, as access permissions will be set accordingly.
2. Always configure your connections using the mqtt.ideate.cmu.edu hostname. Rely on DNS to resolve this to the proper IP address.
   • TLS validation for encrypted communication may fail otherwise.
   • Furthermore, the IP address for this mqtt service may change over time without notice to endusers.
3. Configure your connections to use TLS over the port indicated for your course in the table of registered ports above and the credentials provided by your instructor(s) to your class, team, or group.

3. Testing basic pub/sub from command line

• Linux: On most distributions, simply:
  1. apt-get install mosquitto-clients (or similar for your distribution's package manager)
• Windows 10 (version 1709 or newer):
  1. Follow these instructions to activate Windows Subsystem for Linux, install the Ubuntu environment, launch it, and set it up.
  2. Once at the Ubuntu command prompt, run sudo apt-get install mosquitto-clients to install the client tools.
• macOS:
  1. Install Homebrew if you don't have it already.
  2. brew install mosquitto

Common command-line pub/sub tasks:

Publish to a topic	mosquitto_pub --capath /etc/ssl/certs -h mqtt.ideate.cmu.edu -p «port» -u «username» -P «password» -t '«topic»' -m '«message»'
Subscribe to a topic	mosquitto_sub --capath /etc/ssl/certs -h mqtt.ideate.cmu.edu -p «port» -u «username» -P «password» -t '«topic»' -v (Ctrl-C to cancel when done)

Full documentation on mosquitto_pub
Full documentation on mosquitto_sub

Note: On most platforms as described above, --capath /etc/ssl/certs should correctly load the necessary TLS certificate chains for encrypted communication. If it doesn't, either point with --capath to the correct location for your machine's local certificate store, or download the USERTrust RSA CA root certificate and point directly to it with --cafile usertrust_rsa_ca.crt instead.

Subscribing to a topic such as ‘foo/#’ will subscribe you to the entire ‘foo’ message tree, subject to the permissions granted to your credential. Be careful to ensure that special characters such as ‘#’ are properly quoted, so they are not expanded by your shell.

4. Responsible use

Although the mqtt communication protocol is known for being lightweight, this is still a shared server with finite resources. Please be thoughtful and responsible when determining appropriate publish rates and subscriber counts for your projects. Those found to be causing issues will be warned. Further violations will be considered cause for revocation of access.

Instructor guide: Instance/port management

Configuration for each mosquitto server instance is stored in /opt/mosquitto/«instance_id»/ and is managed using command-line tools. The instance ID is generally the canonical course number, including the hyphen. Refer to the port assignment list.

1. User management

mqtt username/password credential pairs for your instance are stored (with passwords encrypted) in the passwd file. This file should NOT be modified directly, but rather with the mosquitto_passwd command-line tool.

Common user management tasks, assuming you are in your instance's configuration directory:

List all users	cut -d: -f1 passwd | sort
Create a new user (or change an existing user's password)	mosquitto_passwd passwd «username» (Enter new password at both prompts)
Remove a user	mosquitto_passwd -D passwd «username»
Backup and remove all users (see warning below)	mv passwd passwd.old ; touch passwd
Restore backed up users	cp -a passwd.old passwd

Full documentation on mosquitto_passwd

Warning: Removing all users from the passwd file will allow any login and cause all access to be completely unathenticated and available to the public Internet. To help prevent this type of misconfiguration, a new server instance will generally be provided with a fake "REPLACE_ME" user credential which has been intentionally corrupted.

In general, each mqtt credential should be designed to be shareable to an entire class or a small group/team of students. As such, do NOT use valuable passwords for mqtt credentials. These credentials mainly serve to separate concerns or access between disparate teams, and should generally not be assumed to provide strong authentication.

If your curriculum will tend to see mqtt used asymmetrically, e.g., with one classification of "listener" devices mostly subscribing and another classification of "controller" devices mostly publishing, you may wish to provide groups/teams with separate sets of credentials with separate access permissions for these "listeners" and "controllers", both as a best security practice and to help prevent the wrong devices from publishing where they shouldn't.

Instructors are expected to track all issued mqtt credentials and the endusers to whom they are given, as well as to furnish this information to IDeATe technical staff upon request. Since the passwords are encrypted on the server, instructors may also wish to record the original passwords to assist in recovery if necessary; however, it should be sufficient to reset a lost password using the mechanism described above.

2. Access management

mqtt ACLs are evaluated from directives listed in the acl file. This file can be edited with your preferred terminal-based text editor. Note:

• topic directives appearing in the ACL before the first user directive apply only to anonymous users and should be avoided.
• pattern directives always apply to all users, to allow for string/username interpolation, as demonstrated in the examples below.
• ACLs apply, by default, only to the exact topic specified. If you want to provide access to a full message (sub)tree, which is more typical, append /# to the end of the tree path.

Remember: "User" here means a credential, which should generally map to a small group or team, not an individual person.

Common ACL directives:

Allow server metadata to be visible to public	pattern read $SYS/#
Give each user their own privately-writable tree	pattern readwrite private/%u/#
Allow public to read all user-controlled trees	pattern read public/# pattern readwrite public/%u/#
Allow public to read a tree published by a specific user	pattern read mystuff/# user me topic readwrite mystuff/#
Allow private collaboration between two users	user me topic readwrite ourstuff/# user you topic readwrite ourstuff/#

Full documentation on acl_file directives

3. Restarting your instance to effectuate user/access changes

When user or access changes are made, the mosquitto service must be restarted for changes to take effect. Limited sudo rules have been established to allow instance managers to restart their own instance without involving an administrator.

To restart a server instance, run: sudo systemctl restart mosquitto@«instance_id»

The instance ID is generally the canonical course number, including the hyphen. Refer to the port assignment list. Only the exact command specified above can be run with sudo.

4. Testing basic pub/sub from command line

The mosquitto client command-line tools are already installed on the host server, so once logged in, you can test pub/sub from the command line as described in the student guide above. Note that the full hostname, mqtt.ideate.cmu.edu, must still be specified with the -h flag for successful TLS validation, even when running locally on the host server.

5. Logging

Logging records error, warning, notice, information, subscribe, and unsubscribe events to the logs/ subdirectory. Logs are automatically rotated and the latest logfile is symlinked into the instance's main configuration directory at mosquitto.log.

6. Other configuration

If you believe your course will require arbitrary configuration changes to the mosquitto.conf file which go beyond the defaults provided by IDeATe, submit a request to help@ideate.cmu.edu to initiate a discussion on what can reasonably be accommodated considering the various shared uses of this server.