xref: /freebsd/sbin/umbctl/umbctl.8 (revision dd3603749cb7f20a628f04d595b105962b21a3d2)
1.\"-
2.\" SPDX-License-Identifier: BSD-2-Clause
3.\"
4.\" Copyright (c) 2018 by Pierre Pronchery <khorben@defora.org>
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
16.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18.\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
19.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
23.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
24.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25.\" POSSIBILITY OF SUCH DAMAGE.
26.\"
27.\" From: pppoectl.8,v 1.30 2016/09/12 05:35:20 sevan Exp $
28.\"
29.\" $NetBSD: umbctl.8,v 1.3 2020/03/22 07:45:02 khorben Exp $
30.\"
31.\" last edit-date: [Fri Dec 20 18:20:00 2024]
32.\"
33.Dd December 20, 2024
34.Dt UMBCTL 8
35.Os
36.Sh NAME
37.Nm umbctl
38.Nd display or set MBIM cellular modem interface parameters (4G/LTE)
39.Sh SYNOPSIS
40.Nm
41.Op Fl v
42.Ar ifname
43.Op Ar parameter Op Ar value
44.Ar ...
45.Nm
46.Op Fl v
47.Fl f Ar config-file
48.Ar ifname
49.Sh DESCRIPTION
50.Nm
51supports the following options:
52.Bl -tag -width "-f config_file"
53.It Fl f Ar config-file
54Parse
55.Ar config-file
56for
57.Ar parameter Ns Op \&= Ns Ar value
58pairs, one per line, as if they had been specified on the command line.
59This allows the password or PIN codes to be not passed as command line
60arguments.
61Comments starting with # to the end of the current line are ignored.
62.It Fl v
63Enables verbose mode.
64.El
65.Pp
66The
67.Xr umb 4
68driver may require a number of additional arguments or optional
69parameters besides the settings that can be adjusted with
70.Xr ifconfig 8 .
71These may be credentials or other tunable connectivity variables.
72The
73.Nm
74utility can be used to display the current settings, or to adjust these
75parameters as required.
76.Pp
77For whatever intent
78.Nm
79is being called, at least the parameter
80.Ar ifname
81needs to be specified, naming the interface for which the settings
82are to be performed or displayed.
83Use
84.Xr ifconfig 8
85or
86.Xr netstat 1
87to see which interfaces are available.
88.Pp
89If no other parameter is given,
90.Nm
91will just list the current status for
92.Ar ifname
93and exit.
94.Pp
95If any additional parameter is supplied, superuser privileges are
96required, and the command works in
97.Ql set
98mode.
99This is normally done quietly, unless the option
100.Fl v
101is also enabled, which will cause a final printout of the status as
102described above once all other actions have been taken.
103.Pp
104The parameters currently supported include:
105.Bl -tag -width "username=username"
106.It Ar apn Ns \&= Ns Em access-point
107Set the APN to
108.Em access-point .
109.It Ar username Ns \&= Ns Em username
110Set the username to
111.Em username .
112.It Ar password Ns \&= Ns Em password
113Set the password to
114.Em password .
115.It Ar pin Ns \&= Ns Em pin-code
116Enter the PIN
117.Em pin-code .
118.It Ar puk Ns \&= Ns Em puk-code
119Enter the PUK
120.Em puk-code .
121.It Ar roaming
122Allow data connections when roaming.
123.It Ar -roaming
124Deny data connections when roaming.
125.El
126.Sh EXAMPLES
127Display the settings for umb0:
128.Bd -literal
129# umbctl umb0
130umb0: state up, mode automatic, registration home network
131	provider "BSD-Net", dataclass LTE, signal good
132	phone number "+15554242", roaming "" (denied)
133	APN "", TX 50000000, RX 100000000
134	firmware "MBIM_FW_V1.0", hardware "MBIM_HW_V1.0"
135.Ed
136.Pp
137Configure the connection parameters for umb0 from the command line:
138.Bd -literal
139# umbctl umb0 apn operator.internet username mobile password mobile
140.Ed
141.Pp
142Configure the connection parameters for umb0 from a file:
143.Bd -literal
144# umbctl -f /dev/stdin umb0 << EOF
145pin=1234
146EOF
147.Ed
148.Sh SEE ALSO
149.Xr netstat 1 ,
150.Xr umb 4 ,
151.Xr ifconfig 8
152.Sh HISTORY
153The
154.Nm
155utility first appeared in
156.Nx 9.0 ,
157and
158.Fx 15.0 .
159.Sh AUTHORS
160The program was written by
161.An Pierre Pronchery .
162