.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "comitup" "8" "July 2021" "" ""
.hy
.SH NAME
.PP
comitup \- Manage wifi connections on headless, unconnected systems
.SS SYNOPSIS
.PP
\f[V]comitup [options]\f[R]
.SS DESCRIPTION
.PP
The \f[B]comitup\f[R] service provides a means to establish a connection
between a computer and a wifi access point, in the case where wifi is
the only means available to access the computer.
.PP
On startup, the service will attempt to connect to wifi using
established networkmanager(8) connections.
If this is not successful, \f[B]comitup\f[R] will establish a wifi
hotspot with the name \f[I]comitup-<nnn>\f[R], where <nnn> is a
persistent number.
.PP
While the hotspot is active, a comitup-web(8) service is available to
manage connecting to an access point.
A captive portal environment is established to aid in discovery of the
web service.
.PP
If two wifi interfaces are available, the hotspot will remain active on
the first interface, and the internet connection will be made on the
second.
Otherwise, the hotspot will be replaced with the internet connection.
.PP
In all states, avahi-daemon(8) is used to publish the mdns host name
\f[I]comitup-<nnn>.local\f[R], making the web service accessible as
e.g.\ \f[I]http://comitup-123.local\f[R], for systems supporting
Zeroconf.
For other systems, a \f[I]comitup\f[R] Workstation entry is published
which is visible to Zeroconf browsing applications, allowing the IP
address to be manually determined.
The web service address is \f[I]http://10.41.0.1\f[R].
.PP
\f[B]comitup\f[R] logs to \f[I]/var/log/comitup.log\f[R].
.SS Options
.IP \[bu] 2
\f[I]-h\f[R], \f[I]\-help\f[R] - Print help and exit
.IP \[bu] 2
\f[I]-c\f[R], \f[I]\-check\f[R] - Check the wifi device configuration
and exit
.IP \[bu] 2
\f[I]-i\f[R], \f[I]\-info\f[R] - Print info about the current
configuration, and exit
.IP \[bu] 2
\f[I]-v\f[R], \f[I]\-verbose\f[R] - Increase logging to
\f[I]/var/log/comitup.log\f[R]
.SS D-Bus Interface
.PP
\f[B]Comitup\f[R] provides a D-Bus object which claims the name
\f[I]com.github.davesteele.comitup\f[R] on the path
\f[I]/com/github/davesteele/comitup\f[R], supporting the interface
\f[I]com.github.davesteele.comitup\f[R].
The interface includes the following methods.
.IP \[bu] 2
\f[I]get_info()\f[R]
.RS 2
.PP
Input: None
.PP
Output: \f[I]DICT_ENTRY\f[R]
.PP
Return information about the current \f[B]Comitup\f[R] service.
The keys are as follows:
.IP \[bu] 2
\f[I]version\f[R] - The package version.
.IP \[bu] 2
\f[I]apname\f[R] - The currently configured AP hotspot name.
.IP \[bu] 2
\f[I]hostnames\f[R] - A list of host names that are published for the
service IP address.
.IP \[bu] 2
\f[I]imode\f[R] - The current interface mode for comitup.
This returns the string `single' or `router'.
In `single' mode, the hotspot is terminated when \f[B]CONNECTED\f[R].
In `router' mode, the hotspot is retained, the upstream connection is
made with the other wifi device, and traffic is routed between them.
The web service is terminated when \f[B]CONNECTED\f[R].
.RE
.IP \[bu] 2
\f[I]access_points()\f[R]
.RS 2
.PP
Input: None
.PP
Output: Array of \f[I]DICT_ENTRY\f[R]
.PP
Return a list of visible access points.
This is represented as an array of D-Bus \f[I]DICT_ENTRY\f[R].
Each \f[I]DICT_ENTRY\f[R] contains strings associated with the following
keys, \f[I]ssid\f[R], \f[I]strength\f[R] (0 to 100) and
\f[I]security\f[R] (\f[I]encrypted\f[R] or \f[I]unencrypted\f[R]).
.RE
.IP \[bu] 2
\f[I]state()\f[R]
.RS 2
.PP
Input: None
.PP
Output: \f[I]state\f[R], \f[I]connection\f[R]
.PP
This returns strings for the current \f[B]comitup\f[R] state (either
\f[B]HOTSPOT\f[R], \f[B]CONNECTING\f[R], or \f[B]CONNECTED\f[R]) and the
\f[I]ssid\f[R] name for the current connection on the wifi device.
.RE
.IP \[bu] 2
\f[I]connect()\f[R]
.RS 2
.PP
Input: \f[I]ssid\f[R], \f[I]password\f[R]
.PP
Output: None
.PP
Delete any existing connection for \f[I]ssid\f[R], create a new
connection, and attempt to connect to it.
The password may be a zero length string if not needed.
.RE
.IP \[bu] 2
\f[I]delete_connection()\f[R]
.RS 2
.PP
Input: \f[I]ssid\f[R]
.PP
Output: None
.PP
Delete the connection for \f[I]ssid\f[R].
The system will not be able to reconnect using this connection.
.RE
.IP \[bu] 2
\f[I]nuke()\f[R]
.RS 2
.PP
Input: None
.PP
Output: None
.PP
Perform a factory reset of Comitup information on the device, which
consists of removing all WiFi connections, and restarting the service.
Note that \f[I]enable_nuke\f[R] must be enabled in comitup.conf for this
to succeed.
.RE
.SS COPYRIGHT
.PP
Comitup is Copyright (C) 2016-2019 David Steele <steele\[at]debian.org>.
.SS SEE ALSO
.PP
comitup-conf(5), comitup-cli(1), comitup-web(8), comitup-watch(1)