| 1 |
% comitup(8) |
| 2 |
% |
| 3 |
% April 2026 |
| 4 |
|
| 5 |
# NAME |
| 6 |
|
| 7 |
comitup -- Manage wifi connections on headless, unconnected systems |
| 8 |
|
| 9 |
## SYNOPSIS |
| 10 |
|
| 11 |
`comitup [options]` |
| 12 |
|
| 13 |
## DESCRIPTION |
| 14 |
|
| 15 |
The **comitup** service provides a means to establish a connection between a |
| 16 |
computer and a wifi access point, in the case where wifi is the only means |
| 17 |
available to access the computer. |
| 18 |
|
| 19 |
On startup, the service will attempt to connect to wifi using established |
| 20 |
networkmanager(8) connections. If this is not successful, **comitup** will |
| 21 |
establish a wifi hotspot with the name _comitup-<nnn>_, where <nnn> |
| 22 |
is a persistent number. |
| 23 |
|
| 24 |
While the hotspot is active, a comitup-web(8) service is available to manage |
| 25 |
connecting to an access point. A captive portal environment is |
| 26 |
established to aid in discovery of the web service. |
| 27 |
|
| 28 |
If two wifi interfaces are available, the hotspot will remain active on the |
| 29 |
first interface, and the internet connection will be made on the second. |
| 30 |
Otherwise, the hotspot will be replaced with the internet connection. |
| 31 |
|
| 32 |
In all states, avahi-daemon(8) is used to publish the mdns host name |
| 33 |
_comitup-<nnn>.local_, making the web service accessible |
| 34 |
as e.g. _http://comitup-123.local_, for systems supporting Zeroconf. For other |
| 35 |
systems, a _comitup_ Workstation entry is published which is visible to Zeroconf |
| 36 |
browsing applications, allowing the IP address to be manually determined. |
| 37 |
The web service address is _http://10.41.0.1_. |
| 38 |
|
| 39 |
**comitup** logs to _/var/log/comitup.log_. |
| 40 |
|
| 41 |
## Options |
| 42 |
* _-h_, _--help_ - Print help and exit |
| 43 |
* _-c_, _--check_ - Check the wifi device configuration and exit |
| 44 |
* _-i_, _--info_ - Print info about the current configuration, and exit |
| 45 |
* _-v_, _--verbose_ - Increase logging to _/var/log/comitup.log_ |
| 46 |
|
| 47 |
## D-Bus Interface |
| 48 |
|
| 49 |
**Comitup** provides a D-Bus object which claims the name |
| 50 |
_com.github.davesteele.comitup_ on the path |
| 51 |
_/com/github/davesteele/comitup_, supporting the |
| 52 |
interface _com.github.davesteele.comitup_. The interface includes the |
| 53 |
following methods. |
| 54 |
|
| 55 |
* _get_info()_ |
| 56 |
|
| 57 |
Input: None |
| 58 |
|
| 59 |
Output: _DICT_ENTRY_ |
| 60 |
|
| 61 |
Return information about the current **Comitup** service. The keys are |
| 62 |
as follows: |
| 63 |
|
| 64 |
* _version_ - The package version. |
| 65 |
|
| 66 |
* _apname_ - The currently configured AP hotspot name. |
| 67 |
|
| 68 |
* _hostnames_ - A list of host names that are published for the service |
| 69 |
IP address. |
| 70 |
|
| 71 |
* _imode_ - The current interface mode for comitup. This returns the string |
| 72 |
'single' or 'router'. In 'single' mode, the hotspot is terminated when |
| 73 |
**CONNECTED**. In 'router' mode, the hotspot is retained, the upstream |
| 74 |
connection is made with the other wifi device, and traffic is routed |
| 75 |
between them. The web service is terminated when **CONNECTED**. |
| 76 |
|
| 77 |
* _access_points()_ |
| 78 |
|
| 79 |
Input: None |
| 80 |
|
| 81 |
Output: Array of _DICT_ENTRY_ |
| 82 |
|
| 83 |
Return a list of visible access points. This is represented as an array |
| 84 |
of D-Bus _DICT_ENTRY_. Each _DICT_ENTRY_ contains strings associated with |
| 85 |
the following keys, _ssid_, _strength_ (0 to 100) and _security_ |
| 86 |
(_encrypted_ or _unencrypted_). |
| 87 |
|
| 88 |
* _state()_ |
| 89 |
|
| 90 |
Input: None |
| 91 |
|
| 92 |
Output: _state_, _connection_ |
| 93 |
|
| 94 |
This returns strings for the current **comitup** state (either |
| 95 |
**HOTSPOT**, **CONNECTING**, or **CONNECTED**) and the _ssid_ name for |
| 96 |
the current connection on the wifi device. |
| 97 |
|
| 98 |
* _connect()_ |
| 99 |
|
| 100 |
Input: _ssid_, _password_ |
| 101 |
|
| 102 |
Output: None |
| 103 |
|
| 104 |
Delete any existing connection for _ssid_, create a new connection, and |
| 105 |
attempt to connect to it. The password may be a zero length string if |
| 106 |
not needed. |
| 107 |
|
| 108 |
* _delete_connection()_ |
| 109 |
|
| 110 |
Input: _ssid_ |
| 111 |
|
| 112 |
Output: None |
| 113 |
|
| 114 |
Delete the connection for _ssid_. The system will not be able to reconnect |
| 115 |
using this connection. |
| 116 |
|
| 117 |
* _nuke()_ |
| 118 |
|
| 119 |
Input: None |
| 120 |
|
| 121 |
Output: None |
| 122 |
|
| 123 |
Perform a factory reset of Comitup information on the device, which |
| 124 |
consists of removing all WiFi connections, and restarting the service. Note |
| 125 |
that _enable\_nuke_ must be enabled in comitup.conf for this to succeed. |
| 126 |
|
| 127 |
## COPYRIGHT |
| 128 |
|
| 129 |
Comitup is Copyright (C) 2016-2019 David Steele <[email protected]>. |
| 130 |
|
| 131 |
## SEE ALSO |
| 132 |
|
| 133 |
comitup-conf(5), comitup-cli(1), comitup-web(8), comitup-watch(1) |