Index: head/lib/libdpv/dpv.3 =================================================================== --- head/lib/libdpv/dpv.3 (revision 276292) +++ head/lib/libdpv/dpv.3 (revision 276293) @@ -1,510 +1,510 @@ .\" Copyright (c) 2013-2014 Devin Teske .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd Oct 24, 2014 .Dt DPV 3 .Os .Sh NAME .Nm dpv .Nd dialog progress view library .Sh LIBRARY .Lb libdpv .Sh SYNOPSIS .In dpv.h .Ft int .Fo dpv .Fa "struct dpv_config *config, struct dpv_file_node *file_list" .Fc .Ft void .Fo dpv_free .Fa "void" .Fc .Sh DESCRIPTION The .Nm library provides an interface for creating complex .Dq gauge widgets for displaying progress on various actions. The .Nm library can display progress with one of .Xr dialog 3 , .Xr dialog 1 , or .Xr Xdialog 1 .Pq x11/xdialog from the ports tree . .Pp The .Fn dpv .Fa config argument contains the following properties for configuring global display features: .Bd -literal -offset indent struct dpv_config { enum dpv_display display_type; /* Def. DPV_DISPLAY_LIBDIALOG */ enum dpv_output output_type; /* Default DPV_OUTPUT_NONE */ int debug; /* Enable debug on stderr */ int display_limit; /* Files/page. Default -1 */ int label_size; /* Label size. Default 28 */ int pbar_size; /* Mini-progress size */ int dialog_updates_per_second; /* Default 16 */ int status_updates_per_second; /* Default 2 */ uint16_t options; /* Default 0 (none) */ char *title; /* Widget title */ char *backtitle; /* Widget backtitle */ char *aprompt; /* Append. Default NULL */ char *pprompt; /* Prefix. Default NULL */ char *msg_done; /* Default `Done' */ char *msg_fail; /* Default `Fail' */ char *msg_pending; /* Default `Pending' */ char *output; /* Output format string */ const char *status_solo; /* dialog(3) solo-status format. * Default DPV_STATUS_SOLO */ const char *status_many; /* dialog(3) many-status format. * Default DPV_STATUS_MANY */ /* * Function pointer; action to perform data transfer */ int (*action)(struct dpv_file_node *file, int out); }; enum dpv_display { DPV_DISPLAY_LIBDIALOG = 0, /* Use dialog(3) (default) */ DPV_DISPLAY_STDOUT, /* Use stdout */ DPV_DISPLAY_DIALOG, /* Use spawned dialog(1) */ DPV_DISPLAY_XDIALOG, /* Use spawned Xdialog(1) */ }; enum dpv_output { DPV_OUTPUT_NONE = 0, /* No output (default) */ DPV_OUTPUT_FILE, /* Read `output' member as file path */ DPV_OUTPUT_SHELL, /* Read `output' member as shell cmd */ }; .Ed .Pp The .Va options member of the .Fn dpv .Fa config argument is a mask of bit fields indicating various processing options. Possible flags are as follows: .Bl -tag -width DPV_NO_OVERRUN .It Dv DPV_TEST_MODE Enable test mode. In test mode, the .Fn action callback of the .Fa config argument is not called but instead simulated-data is used to drive progress. Appends .Dq [TEST MODE] to the status line .Po to override, set the .Va status_format member of the .Fn dpv .Fa config argument; e.g., to .Dv DPV_STATUS_DEFAULT .Pc . .It Dv DPV_WIDE_MODE Enable wide mode. In wide mode, the length of the .Va aprompt and .Va pprompt members of the .Fn dpv .Fa config argument will bump the width of the gauge widget. Prompts wider than the maximum width will wrap .Po unless using .Xr Xdialog 1 ; see BUGS section below .Pc . .It Dv DPV_NO_LABELS Disables the display of labels associated with each transfer .Po .Va label_size member of .Fn dpv .Fa config argument is ignored .Pc . .It Dv DPV_USE_COLOR Force the use of color even if the .Va display_type does not support color .Po .Ev USE_COLOR environment variable is ignored .Pc . .It Dv DPV_NO_OVERRUN When enabled, callbacks for the current .Vt dpv_file_node are terminated when .Fn action returns 100 or greater .Po alleviates the need to change the .Va status of the current .Vt dpv_file_node but may also cause file truncation if the stream exceeds expected length .Pc . .El .Pp The .Fa file_list argument to .Fn dpv is a pointer to a .Dq linked-list , described as follows in .In dpv.h : .Bd -literal -offset indent struct dpv_file_node { enum dpv_status status; /* status of read operation */ char *msg; /* display instead of "Done/Fail" */ char *name; /* name of file to read */ char *path; /* path to file */ long long length; /* expected size */ long long read; /* number units read (e.g., bytes) */ struct dpv_file_node *next;/* pointer to next (end with NULL) */ }; .Ed .Pp For each of the items in the .Fa file_list .Dq linked-list argument, the .Fn action callback member of the .Fn dpv .Fa config argument is called. The .Fn action function should perform a .Dq nominal action on the file and return. The return value of .Vt int represents the current progress percentage .Pq 0-100 for the current file. .Pp The .Fn action callback provides two variables for each call. .Fa file provides a reference to the current .Vt dpv_file_node being processed. .Fa out provides a file descriptor where the data should go. .Pp If the .Va output member of the .Fn dpv .Fa config argument was set to DPV_OUTPUT_NONE .Pq default ; when invoking Fn dpv , the .Fa out file descriptor of .Fn action will be zero and should be ignored. If .Fa output was set to DPV_OUTPUT_FILE, .Fa out will be an open file descriptor to a file. If .Fa output was set to DPV_OUTPUT_SHELL, .Fa out will be an open file descriptor to a pipe for a spawned shell program. When .Fa out is greater than zero, you should write any data you have read back to .Fa out . .Pp To abort .Fn dpv , either from the .Fn action callback or asynchronously from a signal handler, two globals are provided via .In dpv.h : .Bd -literal -offset indent extern int dpv_interrupt; /* Set to TRUE in interrupt handler */ extern int dpv_abort; /* Set to true in callback to abort */ .Ed .Pp These globals are not automatically reset and must be manually maintained. Don't forget to reset these globals before subsequent invocations of .Fn dpv when making multiple calls from the same program. .Pp In addition, the .Va status member of the .Fn action .Fa file argument can be used to control callbacks for the current file. The .Va status member can be set to any of the following from .In dpv.h : .Bd -literal -offset indent enum dpv_status { DPV_STATUS_RUNNING = 0, /* Running (default) */ DPV_STATUS_DONE, /* Completed */ DPV_STATUS_FAILED, /* Oops, something went wrong */ }; .Ed .Pp The default .Fa status is zero, DPV_STATUS_RUNING, which keeps the callbacks coming for the current .Fn file . Setting .Ql file->status to anything other than DPV_STATUS_RUNNING will cause .Fn dpv to loop to the next file, effecting the next callback, if any. .Pp The .Fn action callback is responsible for calculating percentages and .Pq recommended maintaining a .Nm global counter so .Fn dpv can display throughput statistics. Percentages are reported through the .Vt int return value of the .Fn action callback. Throughput statistics are calculated from the following global .Vt int in .In dpv.h : .Bd -literal -offset indent extern int dpv_overall_read; .Ed .Pp This should be set to the number of bytes that have been read for all files. Throughput information is displayed in the status line .Pq only available when using Xr dialog 3 at the bottom of the screen. See DPV_DISPLAY_LIBDIALOG above. .Pp Note that .Va dpv_overall_read does not have to represent bytes. For example, you can change the .Va status_format to display something other than .Dq Li bytes and increment .Va dpv_overall_read accordingly .Pq e.g., counting lines . .Pp When .Fn dpv is processing the current file, the .Va length and .Va read members of the .Fn action .Fa file argument are used for calculating the display of mini progress bars .Po if enabled; see .Va pbar_size above .Pc . If the .Va length member of the current .Fa file is less than zero .Pq indicating an unknown file length , a .Xr humanize_number 3 version of the .Va read member is used instead of a traditional progress bar. Otherwise a progress bar is calculated as percentage read to file length. .Fn action callback must maintain these member values for mini-progress bars. .Pp The .Fn dpv_free function performs .Xr free 3 on private global variables initialized by .Fn dpv . .Sh ENVIRONMENT The following environment variables are referenced by .Nm : .Bl -tag -width ".Ev USE_COLOR" .It Ev DIALOG Override command string used to launch .Xr dialog 1 .Pq requires Dv DPV_DISPLAY_DIALOG or .Xr Xdialog 1 .Pq requires Dv DPV_DISPLAY_XDIALOG ; default is either .Ql dialog .Pq for Dv DPV_DISPLAY_DIALOG or .Ql Xdialog .Pq for Dv DPV_DISPLAY_XDIALOG . .It Ev DIALOGRC If set and non-NULL, path to .Ql .dialogrc file. .It Ev HOME If .Ql Ev $DIALOGRC is either not set or NULL, used as a prefix to .Ql .dialogrc .Pq i.e., Ql $HOME/.dialogrc . .It Ev USE_COLOR If set and NULL, disables the use of color when using .Xr dialog 1 .Pq does not apply to Xr Xdialog 1 . .It Ev msg_done Ev msg_fail Ev msg_pending Internationalization strings for overriding the default English strings .Ql Done , .Ql Fail , and .Ql Pending respectively. To prevent their usage, explicitly set the .Va msg_done , .Va msg_fail , and .Va msg_pending members of .Fn dpv .Fa config argument to default macros .Pq DPV_DONE_DEFAULT, DPV_FAIL_DEFAULT, and DPV_PENDING_DEFAULT or desired values. .El .Sh FILES .Bl -tag -width ".Pa $HOME/.dialogrc" -compact .It Pa $HOME/.dialogrc .El .Sh SEE ALSO .Xr dialog 1 , -.Xr dialog 3 , -.Xr Xdialog 1 +.Xr Xdialog 1 , +.Xr dialog 3 .Sh HISTORY The .Nm library first appeared in .Fx 11.0 . .Sh AUTHORS .An Devin Teske Aq dteske@FreeBSD.org .Sh BUGS .Xr Xdialog 1 , when given both .Ql Fl -title Ar title .Po see above .Ql Va title member of .Va struct dpv_config .Pc and .Ql Fl -backtitle Ar backtitle .Po see above .Ql Va backtitle member of .Va struct dpv_config .Pc , displays the backtitle in place of the title and vice-versa. .Pp .Xr Xdialog 1 does not wrap long prompt texts received after initial launch. This is a known issue with the .Ql --gauge widget in .Xr Xdialog 1 . Embed escaped newlines within prompt text(s) to force line breaks. .Pp .Xr dialog 1 does not display the first character after a series of escaped escape-sequences (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n''). This is a known issue with .Xr dialog 1 and does not affect .Xr dialog 3 or .Xr Xdialog 1 . .Pp If your application ignores .Ev USE_COLOR when set and NULL before calling .Xr dpv 3 with color escape sequences anyway, .Xr dialog 3 and .Xr dialog 1 may not render properly. Workaround is to detect when .Ev USE_COLOR is set and NULL and either not use color escape sequences at that time or use .Xr unsetenv 3 to unset .Ev USE_COLOR , forcing interpretation of color sequences. This does not effect .Xr Xdialog 1 , which renders the color escape sequences as plain text. See .Do embedded "\\Z" sequences .Dc in .Xr dialog 1 for additional information. Index: head/lib/msun/man/cexp.3 =================================================================== --- head/lib/msun/man/cexp.3 (revision 276292) +++ head/lib/msun/man/cexp.3 (revision 276293) @@ -1,113 +1,113 @@ .\" Copyright (c) 2011 David Schultz .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 6, 2011 .Dt CEXP 3 .Os .Sh NAME .Nm cexp , .Nm cexpf .Nd complex exponential functions .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In complex.h .Ft double complex .Fn cexp "double complex z" .Ft float complex .Fn cexpf "float complex z" .Sh DESCRIPTION The .Fn cexp and .Fn cexpf functions compute the complex exponential of .Fa z , also known as .Em cis Ns ( Ns .Fa z Ns ) . .Sh RETURN VALUES For real numbers .Fa x and .Fa y , .Fn cexp behaves according to Euler's formula: .Bd -ragged -offset indent .Fn cexp "x + I*y" = .Po Sy e Ns ** Ns .Fa x * .Em cos Ns Po Ns .Fa y Ns Pc Pc + Po Ns .Sy I * .Sy e Ns ** Ns .Fa x * .Em sin Ns Po Ns .Fa y Ns Pc Pc .Ed .Pp Generally speaking, infinities, zeroes and \*(Nas are handled as would be expected from this identity given the usual rules of floating-point arithmetic. However, care is taken to avoid generating \*(Nas when they are not deserved. For example, mathematically we expect that .Fo cimag .Fn cexp "x + I*0" Fc = 0 regardless of the value of .Fa x , and .Fn cexp preserves this identity even if .Fa x is \*(If or \*(Na. Likewise, .Fn cexp "-\*(If + I*y" = 0 and .Fo creal .Fn cexp "\*(If + I*y" Fc = \*(If for any .Fa y (even though the latter property is only mathematically true for representable .Fa y . ) If .Fa y is not finite, the sign of the result is indeterminate. .Sh SEE ALSO .Xr complex 3 , .Xr exp 3 , -.Xr math 3 , +.Xr math 3 .Sh STANDARDS The .Fn cexp and .Fn cexpf functions conform to .St -isoC-99 . Index: head/lib/msun/man/complex.3 =================================================================== --- head/lib/msun/man/complex.3 (revision 276292) +++ head/lib/msun/man/complex.3 (revision 276293) @@ -1,124 +1,124 @@ .\" Copyright (c) 2011 Murray Stokely .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 17, 2011 .Dt COMPLEX 3 .Os .Sh NAME .Nm complex .Nd "complex arithmetic" .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In complex.h .Sh DESCRIPTION These functions support complex arithmetic in the C math library. .Sh "LIST OF FUNCTIONS" Each of the following .Vt "double complex" functions has a .Vt "float complex" counterpart with an .Ql f appended to the name and a .Vt "long double complex" counterpart with an .Ql l appended. As an example, the .Vt "float complex" and .Vt "long double complex" counterparts of .Ft double .Fn cabs "double complex z" are .Ft float .Fn cabsf "float complex z" and .Ft "long double" .Fn cabsl "long double complex z" , respectively. .de Cl .Bl -column "csqrt" "complex absolute value (i.e. norm, modulus, magnitude)" .Em "Name Description" .. .\" Section 7.3.5 - 7.3.7 of ISO C99 standard unimplemented, see BUGS .\" Section 7.3.8 of ISO C99 standard .Ss Absolute-value Functions .Cl cabs complex absolute value (i.e. norm, modulus, magnitude) csqrt complex square root .El .Ss Exponential Function .Cl cexp exponential base e .El .\" Section 7.3.9 of ISO C99 standard .Ss Manipulation Functions .Cl carg compute the argument (i.e. phase angle) cimag compute the imaginary part conj compute the complex conjugate cproj compute projection onto Riemann sphere creal compute the real part .El .\" Section 7.3.5-6 of ISO C99 standard .Ss Trigonometric and Hyperbolic Functions .Cl cacos arc cosine cacosh arc hyperbolic cosine casin arc sine casinh arc hyperbolic sine catan arc tangent catanh arc hyperbolic tangent ccos cosine ccosh hyperbolic cosine csin sine csinh hyperbolic sine ctan tangent ctanh hyperbolic tangent .El .Sh SEE ALSO -.Xr math 3 , .Xr fenv 3 , .Xr ieee 3 , +.Xr math 3 , .Xr tgmath 3 .Rs .%T "ISO/IEC 9899:TC3" .%U http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf .Re .Sh STANDARDS The .In complex.h functions described here conform to .St -isoC-99 . .Sh BUGS The logarithmic functions .Fn clog and the power functions .Fn cpow are not implemented. Index: head/lib/msun/man/sin.3 =================================================================== --- head/lib/msun/man/sin.3 (revision 276292) +++ head/lib/msun/man/sin.3 (revision 276293) @@ -1,82 +1,82 @@ .\" Copyright (c) 1991 The Regents of the University of California. .\" All rights reserved. .\" .\" @(#)sin.3 6.7 (Berkeley) 4/19/91 .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" from: @(#)sin.3 6.7 (Berkeley) 4/19/91 .\" $FreeBSD$ .\" .Dd January 24, 2008 .Dt SIN 3 .Os .Sh NAME .Nm sin , .Nm sinf , .Nm sinl .Nd sine functions .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In math.h .Ft double .Fn sin "double x" .Ft float .Fn sinf "float x" .Ft long double .Fn sinl "long double x" .Sh DESCRIPTION The .Fn sin , .Fn sinf , and .Fn sinl functions compute the sine of .Fa x (measured in radians). A large magnitude argument may yield a result with little or no significance. .Sh RETURN VALUES The .Fn sin , .Fn sinf , and .Fn sinl functions return the sine value. .Sh SEE ALSO .Xr acos 3 , .Xr asin 3 , .Xr atan 3 , .Xr atan2 3 , -.Xr csin 3 , .Xr cos 3 , .Xr cosh 3 , +.Xr csin 3 , .Xr math 3 , .Xr sinh 3 , .Xr tan 3 , .Xr tanh 3 .Sh STANDARDS These functions conform to .St -isoC-99 . Index: head/sbin/dhclient/dhclient.conf.5 =================================================================== --- head/sbin/dhclient/dhclient.conf.5 (revision 276292) +++ head/sbin/dhclient/dhclient.conf.5 (revision 276293) @@ -1,544 +1,544 @@ .\" $OpenBSD: dhclient.conf.5,v 1.5 2004/11/01 23:10:18 henning Exp $ .\" .\" Copyright (c) 1997 The Internet Software Consortium. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of The Internet Software Consortium nor the names .\" of its contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" This software has been written for the Internet Software Consortium .\" by Ted Lemon in cooperation with Vixie .\" Enterprises. To learn more about the Internet Software Consortium, .\" see ``http://www.isc.org/isc''. To learn more about Vixie .\" Enterprises, see ``http://www.vix.com''. .\" .\" $FreeBSD$ .\" .Dd January 1, 1997 .Dt DHCLIENT.CONF 5 .Os .Sh NAME .Nm dhclient.conf .Nd DHCP client configuration file .Sh DESCRIPTION The .Nm file contains configuration information for .Xr dhclient 8 , the Internet Software Consortium DHCP Client. .Pp The .Nm file is a free-form ASCII text file. It is parsed by the recursive-descent parser built into .Xr dhclient 8 . The file may contain extra tabs and newlines for formatting purposes. Keywords in the file are case-insensitive. Comments may be placed anywhere within the file (except within quotes). Comments begin with the .Ql # character and end at the end of the line. .Pp The .Nm file can be used to configure the behaviour of the client in a wide variety of ways: protocol timing, information requested from the server, information required of the server, defaults to use if the server does not provide certain information, values with which to override information provided by the server, or values to prepend or append to information provided by the server. The configuration file can also be preinitialized with addresses to use on networks that do not have DHCP servers. .Sh PROTOCOL TIMING The timing behaviour of the client need not be configured by the user. If no timing configuration is provided by the user, a fairly reasonable timing behaviour will be used by default - one which results in fairly timely updates without placing an inordinate load on the server. .Pp The following statements can be used to adjust the timing behaviour of the DHCP client if required, however: .Bl -tag -width indent .It Ic timeout Ar time ; The .Ic timeout statement determines the amount of time that must pass between the time that the client begins to try to determine its address and the time that it decides that it is not going to be able to contact a server. By default, this timeout is sixty seconds. After the timeout has passed, if there are any static leases defined in the configuration file, or any leases remaining in the lease database that have not yet expired, the client will loop through these leases attempting to validate them, and if it finds one that appears to be valid, it will use that lease's address. If there are no valid static leases or unexpired leases in the lease database, the client will restart the protocol after the defined retry interval. .It Ic retry Ar time ; The .Ic retry statement determines the time that must pass after the client has determined that there is no DHCP server present before it tries again to contact a DHCP server. By default, this is five minutes. .It Ic select-timeout Ar time ; It is possible (some might say desirable) for there to be more than one DHCP server serving any given network. In this case, it is possible that a client may be sent more than one offer in response to its initial lease discovery message. It may be that one of these offers is preferable to the other (e.g., one offer may have the address the client previously used, and the other may not). .Pp The .Ic select-timeout is the time after the client sends its first lease discovery request at which it stops waiting for offers from servers, assuming that it has received at least one such offer. If no offers have been received by the time the .Ic select-timeout has expired, the client will accept the first offer that arrives. .Pp By default, the .Ic select-timeout is zero seconds - that is, the client will take the first offer it sees. .It Ic reboot Ar time ; When the client is restarted, it first tries to reacquire the last address it had. This is called the INIT-REBOOT state. If it is still attached to the same network it was attached to when it last ran, this is the quickest way to get started. The .Ic reboot statement sets the time that must elapse after the client first tries to reacquire its old address before it gives up and tries to discover a new address. By default, the reboot timeout is ten seconds. .It Ic backoff-cutoff Ar time ; The client uses an exponential backoff algorithm with some randomness, so that if many clients try to configure themselves at the same time, they will not make their requests in lockstep. The .Ic backoff-cutoff statement determines the maximum amount of time that the client is allowed to back off. It defaults to two minutes. .It Ic initial-interval Ar time ; The .Ic initial-interval statement sets the amount of time between the first attempt to reach a server and the second attempt to reach a server. Each time a message is sent, the interval between messages is incremented by twice the current interval multiplied by a random number between zero and one. If it is greater than the .Ic backoff-cutoff amount, it is set to that amount. It defaults to ten seconds. .El .Sh LEASE REQUIREMENTS AND REQUESTS The DHCP protocol allows the client to request that the server send it specific information, and not send it other information that it is not prepared to accept. The protocol also allows the client to reject offers from servers if they do not contain information the client needs, or if the information provided is not satisfactory. .Pp There is a variety of data contained in offers that DHCP servers send to DHCP clients. The data that can be specifically requested is what are called .Em DHCP Options . DHCP Options are defined in .Xr dhcp-options 5 . .Bl -tag -width indent .It Ic request Oo Ar option Oc Oo , Ar ... option Oc ; The .Ic request statement causes the client to request that any server responding to the client send the client its values for the specified options. Only the option names should be specified in the request statement - not option parameters. .It Ic require Oo Ar option Oc Oo , Ar ... option Oc ; The .Ic require statement lists options that must be sent in order for an offer to be accepted. Offers that do not contain all the listed options will be ignored. .It Ic send No { Oo Ar option declaration Oc Oo , Ar ... option declaration Oc } The .Ic send statement causes the client to send the specified options to the server with the specified values. These are full option declarations as described in .Xr dhcp-options 5 . Options that are always sent in the DHCP protocol should not be specified here, except that the client can specify a .Ar dhcp-lease-time option other than the default requested lease time, which is two hours. The other obvious use for this statement is to send information to the server that will allow it to differentiate between this client and other clients or kinds of clients. .El .Sh OPTION MODIFIERS In some cases, a client may receive option data from the server which is not really appropriate for that client, or may not receive information that it needs, and for which a useful default value exists. It may also receive information which is useful, but which needs to be supplemented with local information. To handle these needs, several option modifiers are available. .Bl -tag -width indent .It Xo .Ic default No { Op Ar option declaration .Oo , Ar ... option declaration Oc } .Xc If for some set of options the client should use the value supplied by the server, but needs to use some default value if no value was supplied by the server, these values can be defined in the .Ic default statement. .It Xo .Ic supersede No { Op Ar option declaration .Oo , Ar ... option declaration Oc } .Xc If for some set of options the client should always use its own value rather than any value supplied by the server, these values can be defined in the .Ic supersede statement. .It Xo .Ic prepend No { Op Ar option declaration .Oo , Ar ... option declaration Oc } .Xc If for some set of options the client should use a value you supply, and then use the values supplied by the server, if any, these values can be defined in the .Ic prepend statement. The .Ic prepend statement can only be used for options which allow more than one value to be given. This restriction is not enforced - if violated, the results are unpredictable. .It Xo .Ic append No { Op Ar option declaration .Oo , Ar ... option declaration Oc } .Xc If for some set of options the client should first use the values supplied by the server, if any, and then use values you supply, these values can be defined in the .Ic append statement. The .Ic append statement can only be used for options which allow more than one value to be given. This restriction is not enforced - if you ignore it, the behaviour will be unpredictable. .El .Sh LEASE DECLARATIONS The lease declaration: .Pp .D1 Ic lease No { Ar lease-declaration Oo Ar ... lease-declaration Oc } .Pp The DHCP client may decide after some period of time (see .Sx PROTOCOL TIMING ) that it is not going to succeed in contacting a server. At that time, it consults its own database of old leases and tests each one that has not yet timed out by pinging the listed router for that lease to see if that lease could work. It is possible to define one or more .Em fixed leases in the client configuration file for networks where there is no DHCP or BOOTP service, so that the client can still automatically configure its address. This is done with the .Ic lease statement. .Pp NOTE: the lease statement is also used in the .Pa dhclient.leases file in order to record leases that have been received from DHCP servers. Some of the syntax for leases as described below is only needed in the .Pa dhclient.leases file. Such syntax is documented here for completeness. .Pp A lease statement consists of the .Ic lease keyword, followed by a left curly brace, followed by one or more lease declaration statements, followed by a right curly brace. The following lease declarations are possible: .Bl -tag -width indent .It Ic bootp ; The .Ic bootp statement is used to indicate that the lease was acquired using the BOOTP protocol rather than the DHCP protocol. It is never necessary to specify this in the client configuration file. The client uses this syntax in its lease database file. .It Ic interface Qq Ar string ; The .Ic interface lease statement is used to indicate the interface on which the lease is valid. If set, this lease will only be tried on a particular interface. When the client receives a lease from a server, it always records the interface number on which it received that lease. If predefined leases are specified in the .Nm file, the interface should also be specified, although this is not required. .It Ic fixed-address Ar ip-address ; The .Ic fixed-address statement is used to set the IP address of a particular lease. This is required for all lease statements. The IP address must be specified as a dotted quad (e.g., .Li 12.34.56.78 ) . .It Ic filename Qq Ar string ; The .Ic filename statement specifies the name of the boot filename to use. This is not used by the standard client configuration script, but is included for completeness. .It Ic server-name Qq Ar string ; The .Ic server-name statement specifies the name of the boot server name to use. This is also not used by the standard client configuration script. .It Ic option Ar option-declaration ; The .Ic option statement is used to specify the value of an option supplied by the server, or, in the case of predefined leases declared in .Nm , the value that the user wishes the client configuration script to use if the predefined lease is used. .It Ic script Qq Ar script-name ; The .Ic script statement is used to specify the pathname of the DHCP client configuration script. This script is used by the DHCP client to set each interface's initial configuration prior to requesting an address, to test the address once it has been offered, and to set the interface's final configuration once a lease has been acquired. If no lease is acquired, the script is used to test predefined leases, if any, and also called once if no valid lease can be identified. For more information, see .Xr dhclient.leases 5 . .It Ic medium Qq Ar "media setup" ; The .Ic medium statement can be used on systems where network interfaces cannot automatically determine the type of network to which they are connected. The .Ar "media setup" string is a system-dependent parameter which is passed to the DHCP client configuration script when initializing the interface. On .Ux and .Ux Ns -like systems, the argument is passed on the .Xr ifconfig 8 command line when configuring the interface. .Pp The DHCP client automatically declares this parameter if it used a media type (see the .Ic media statement) when configuring the interface in order to obtain a lease. This statement should be used in predefined leases only if the network interface requires media type configuration. .It Ic renew Ar date ; .It Ic rebind Ar date ; .It Ic expire Ar date ; The .Ic renew statement defines the time at which the DHCP client should begin trying to contact its server to renew a lease that it is using. The .Ic rebind statement defines the time at which the DHCP client should begin to try to contact .Em any DHCP server in order to renew its lease. The .Ic expire statement defines the time at which the DHCP client must stop using a lease if it has not been able to contact a server in order to renew it. .El .Pp These declarations are automatically set in leases acquired by the DHCP client, but must also be configured in predefined leases - a predefined lease whose expiry time has passed will not be used by the DHCP client. .Pp Dates are specified as follows: .Bd -ragged -offset indent .Ar .Sm off .Ar No / Ar No / Ar .Ar : : .Sm on .Ed .Pp The weekday is present to make it easy for a human to tell when a lease expires - it is specified as a number from zero to six, with zero being Sunday. When declaring a predefined lease, it can always be specified as zero. The year is specified with the century, so it should generally be four digits except for really long leases. The month is specified as a number starting with 1 for January. The day of the month is likewise specified starting with 1. The hour is a number between 0 and 23, the minute a number between 0 and 59, and the second also a number between 0 and 59. .Sh ALIAS DECLARATIONS .Ic alias No { Ar declarations ... No } .Pp Some DHCP clients running TCP/IP roaming protocols may require that in addition to the lease they may acquire via DHCP, their interface also be configured with a predefined IP alias so that they can have a permanent IP address even while roaming. The Internet Software Consortium DHCP client does not support roaming with fixed addresses directly, but in order to facilitate such experimentation, the DHCP client can be set up to configure an IP alias using the .Ic alias declaration. .Pp The .Ic alias declaration resembles a lease declaration, except that options other than the subnet-mask option are ignored by the standard client configuration script, and expiry times are ignored. A typical alias declaration includes an interface declaration, a fixed-address declaration for the IP alias address, and a subnet-mask option declaration. A medium statement should never be included in an alias declaration. .Sh OTHER DECLARATIONS .Bl -tag -width indent .It Ic reject Ar ip-address ; The .Ic reject statement causes the DHCP client to reject offers from servers who use the specified address as a server identifier. This can be used to avoid being configured by rogue or misconfigured DHCP servers, although it should be a last resort - better to track down the bad DHCP server and fix it. .It Ic interface Qo Ar name Qc { Ar declarations ... No } A client with more than one network interface may require different behaviour depending on which interface is being configured. All timing parameters and declarations other than lease and alias declarations can be enclosed in an interface declaration, and those parameters will then be used only for the interface that matches the specified name. Interfaces for which there is no interface declaration will use the parameters declared outside of any interface declaration, or the default settings. .It Ic media Qo Ar "media setup" Qc Oo , Qo Ar "media setup" Qc , Ar ... Oc ; The .Ic media statement defines one or more media configuration parameters which may be tried while attempting to acquire an IP address. The DHCP client will cycle through each media setup string on the list, configuring the interface using that setup and attempting to boot, and then trying the next one. This can be used for network interfaces which are not capable of sensing the media type unaided - whichever media type succeeds in getting a request to the server and hearing the reply is probably right (no guarantees). .Pp The media setup is only used for the initial phase of address acquisition (the DHCPDISCOVER and DHCPOFFER packets). Once an address has been acquired, the DHCP client will record it in its lease database and will record the media type used to acquire the address. Whenever the client tries to renew the lease, it will use that same media type. The lease must expire before the client will go back to cycling through media types. .El .Sh EXAMPLES The following configuration file is used on a laptop which has an IP alias of .Li 192.5.5.213 , and has one interface, .Li ep0 (a 3Com 3C589C). Booting intervals have been shortened somewhat from the default, because the client is known to spend most of its time on networks with little DHCP activity. The laptop does roam to multiple networks. .Bd -literal -offset indent timeout 60; retry 60; reboot 10; select-timeout 5; initial-interval 2; reject 192.33.137.209; interface "ep0" { send host-name "andare.fugue.com"; send dhcp-client-identifier 1:0:a0:24:ab:fb:9c; send dhcp-lease-time 3600; supersede domain-name "fugue.com rc.vix.com home.vix.com"; prepend domain-name-servers 127.0.0.1; request subnet-mask, broadcast-address, time-offset, routers, domain-name, domain-name-servers, host-name; require subnet-mask, domain-name-servers; script "/etc/dhclient-script"; media "media 10baseT/UTP", "media 10base2/BNC"; } alias { interface "ep0"; fixed-address 192.5.5.213; option subnet-mask 255.255.255.255; } .Ed .Pp This is a very complicated .Nm file - in general, yours should be much simpler. In many cases, it is sufficient to just create an empty .Nm file - the defaults are usually fine. .Sh SEE ALSO .Xr dhclient.leases 5 , -.Xr dhcpd.conf 5 , .Xr dhcp-options 5 , +.Xr dhcpd.conf 5 , .Xr dhclient 8 , .Xr dhcpd 8 .Rs .%R "RFC 2132, RFC 2131" .Re .Sh AUTHORS .An -nosplit The .Xr dhclient 8 utility was written by .An Ted Lemon Aq Mt mellon@vix.com under a contract with Vixie Labs. .Pp The current implementation was reworked by .An Henning Brauer Aq Mt henning@openbsd.org . Index: head/sbin/dhclient/dhclient.leases.5 =================================================================== --- head/sbin/dhclient/dhclient.leases.5 (revision 276292) +++ head/sbin/dhclient/dhclient.leases.5 (revision 276293) @@ -1,95 +1,95 @@ .\" $OpenBSD: dhclient.leases.5,v 1.4 2004/04/15 08:59:47 jmc Exp $ .\" .\" Copyright (c) 1997 The Internet Software Consortium. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of The Internet Software Consortium nor the names .\" of its contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" This software has been written for the Internet Software Consortium .\" by Ted Lemon in cooperation with Vixie .\" Enterprises. To learn more about the Internet Software Consortium, .\" see ``http://www.isc.org/isc''. To learn more about Vixie .\" Enterprises, see ``http://www.vix.com''. .\" .\" $FreeBSD$ .\" .Dd January 1, 1997 .Dt DHCLIENT.LEASES 5 .Os .Sh NAME .Nm dhclient.leases .Nd DHCP client lease database .Sh DESCRIPTION The Internet Software Consortium DHCP client keeps a persistent database of leases that it has acquired that are still valid. The database is a free-form ASCII file containing one valid declaration per lease. If more than one declaration appears for a given lease, the last one in the file is used. The file is written as a log, so this is not an unusual occurrence. .Pp The lease file is named .Pa dhclient.leases. Ns Ar IFNAME , where .Ar IFNAME represents the network interface the DHCP client acquired the lease on. For example, if .Xr dhclient 8 is configured for the .Li em0 network device, the lease file will be named .Pa dhclient.leases.em0 . .Pp The format of the lease declarations is described in .Xr dhclient.conf 5 . .Sh FILES .Bl -tag -width ".Pa /var/db/dhclient.leases. Ns Ar IFNAME" .It Pa /var/db/dhclient.leases. Ns Ar IFNAME Current lease file. .El .Sh SEE ALSO .Xr dhclient.conf 5 , -.Xr dhcpd.conf 5 , .Xr dhcp-options 5 , +.Xr dhcpd.conf 5 , .Xr dhclient 8 , .Xr dhcpd 8 .Rs .%R "RFC 2132, RFC 2131" .Re .Sh AUTHORS .An -nosplit The .Xr dhclient 8 utility was written by .An Ted Lemon Aq Mt mellon@vix.com under a contract with Vixie Labs. .Pp The current implementation was reworked by .An Henning Brauer Aq Mt henning@openbsd.org . Index: head/sbin/ifconfig/ifconfig.8 =================================================================== --- head/sbin/ifconfig/ifconfig.8 (revision 276292) +++ head/sbin/ifconfig/ifconfig.8 (revision 276293) @@ -1,2844 +1,2844 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" From: @(#)ifconfig.8 8.3 (Berkeley) 1/5/94 .\" $FreeBSD$ .\" .Dd December 16, 2014 .Dt IFCONFIG 8 .Os .Sh NAME .Nm ifconfig .Nd configure network interface parameters .Sh SYNOPSIS .Nm .Op Fl L .Op Fl k .Op Fl m .Op Fl n .Ar interface .Op Cm create .Ar address_family .Oo .Ar address .Op Ar dest_address .Oc .Op Ar parameters .Nm .Ar interface .Cm destroy .Nm .Fl a .Op Fl L .Op Fl d .Op Fl m .Op Fl u .Op Fl v .Op Ar address_family .Nm .Fl l .Op Fl d .Op Fl u .Op Ar address_family .Nm .Op Fl L .Op Fl d .Op Fl k .Op Fl m .Op Fl u .Op Fl v .Op Fl C .Nm .Op Fl g Ar groupname .Sh DESCRIPTION The .Nm utility is used to assign an address to a network interface and/or configure network interface parameters. The .Nm utility must be used at boot time to define the network address of each interface present on a machine; it may also be used at a later time to redefine an interface's address or other operating parameters. .Pp The following options are available: .Bl -tag -width indent .It Ar address For the .Tn DARPA Ns -Internet family, the address is either a host name present in the host name data base, .Xr hosts 5 , or a .Tn DARPA Internet address expressed in the Internet standard .Dq dot notation . .Pp It is also possible to use the CIDR notation (also known as the slash notation) to include the netmask. That is, one can specify an address like .Li 192.168.0.1/16 . .Pp For the .Dq inet6 family, it is also possible to specify the prefix length using the slash notation, like .Li ::1/128 . See the .Cm prefixlen parameter below for more information. .\" For the Xerox Network Systems(tm) family, .\" addresses are .\" .Ar net:a.b.c.d.e.f , .\" where .\" .Ar net .\" is the assigned network number (in decimal), .\" and each of the six bytes of the host number, .\" .Ar a .\" through .\" .Ar f , .\" are specified in hexadecimal. .\" The host number may be omitted on IEEE 802 protocol .\" (Ethernet, FDDI, and Token Ring) interfaces, .\" which use the hardware physical address, .\" and on interfaces other than the first. .\" For the .\" .Tn ISO .\" family, addresses are specified as a long hexadecimal string, .\" as in the Xerox family. .\" However, two consecutive dots imply a zero .\" byte, and the dots are optional, if the user wishes to (carefully) .\" count out long strings of digits in network byte order. .Pp The link-level .Pq Dq link address is specified as a series of colon-separated hex digits. This can be used to, for example, set a new MAC address on an Ethernet interface, though the mechanism used is not Ethernet specific. If the interface is already up when this option is used, it will be briefly brought down and then brought back up again in order to ensure that the receive filter in the underlying Ethernet hardware is properly reprogrammed. .It Ar address_family Specify the address family which affects interpretation of the remaining parameters. Since an interface can receive transmissions in differing protocols with different naming schemes, specifying the address family is recommended. The address or protocol families currently supported are .Dq inet , .Dq inet6 , and .Dq link . The default if available is .Dq inet or otherwise .Dq link . .Dq ether and .Dq lladdr are synonyms for .Dq link . When using the .Fl l flag, the .Dq ether address family has special meaning and is no longer synonymous with .Dq link or .Dq lladdr . Specifying .Fl l Dq ether will list only Ethernet interfaces, excluding all other interface types, including the loopback interface. .It Ar dest_address Specify the address of the correspondent on the other end of a point to point link. .It Ar interface This parameter is a string of the form .Dq name unit , for example, .Dq Li ed0 . .It Ar groupname List the interfaces in the given group. .El .Pp The following parameters may be set with .Nm : .Bl -tag -width indent .It Cm add Another name for the .Cm alias parameter. Introduced for compatibility with .Bsx . .It Cm alias Establish an additional network address for this interface. This is sometimes useful when changing network numbers, and one wishes to accept packets addressed to the old interface. If the address is on the same subnet as the first network address for this interface, a non-conflicting netmask must be given. Usually .Li 0xffffffff is most appropriate. .It Fl alias Remove the network address specified. This would be used if you incorrectly specified an alias, or it was no longer needed. If you have incorrectly set an NS address having the side effect of specifying the host portion, removing all NS addresses will allow you to respecify the host portion. .It Cm anycast (Inet6 only.) Specify that the address configured is an anycast address. Based on the current specification, only routers may configure anycast addresses. Anycast address will not be used as source address of any of outgoing IPv6 packets. .It Cm arp Enable the use of the Address Resolution Protocol .Pq Xr arp 4 in mapping between network level addresses and link level addresses (default). This is currently implemented for mapping between .Tn DARPA Internet addresses and .Tn IEEE 802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses). .It Fl arp Disable the use of the Address Resolution Protocol .Pq Xr arp 4 . .It Cm staticarp If the Address Resolution Protocol is enabled, the host will only reply to requests for its addresses, and will never send any requests. .It Fl staticarp If the Address Resolution Protocol is enabled, the host will perform normally, sending out requests and listening for replies. .It Cm broadcast (Inet only.) Specify the address to use to represent broadcasts to the network. The default broadcast address is the address with a host part of all 1's. .It Cm debug Enable driver dependent debugging code; usually, this turns on extra console error logging. .It Fl debug Disable driver dependent debugging code. .It Cm promisc Put interface into permanently promiscuous mode. .It Fl promisc Disable permanently promiscuous mode. .It Cm delete Another name for the .Fl alias parameter. .It Cm description Ar value , Cm descr Ar value Specify a description of the interface. This can be used to label interfaces in situations where they may otherwise be difficult to distinguish. .It Cm -description , Cm -descr Clear the interface description. .It Cm down Mark an interface .Dq down . When an interface is marked .Dq down , the system will not attempt to transmit messages through that interface. If possible, the interface will be reset to disable reception as well. This action does not automatically disable routes using the interface. .It Cm group Ar group-name Assign the interface to a .Dq group . Any interface can be in multiple groups. .Pp Cloned interfaces are members of their interface family group by default. For example, a PPP interface such as .Em ppp0 is a member of the PPP interface family group, .Em ppp . .\" The interface(s) the default route(s) point to are members of the .\" .Em egress .\" interface group. .It Cm -group Ar group-name Remove the interface from the given .Dq group . .It Cm eui64 (Inet6 only.) Fill interface index (lowermost 64bit of an IPv6 address) automatically. .It Cm fib Ar fib_number Specify interface FIB. A FIB .Ar fib_number is assigned to all frames or packets received on that interface. The FIB is not inherited, e.g., vlans or other sub-interfaces will use the default FIB (0) irrespective of the parent interface's FIB. The kernel needs to be tuned to support more than the default FIB using the .Va ROUTETABLES kernel configuration option, or the .Va net.fibs tunable. .It Cm maclabel Ar label If Mandatory Access Control support is enabled in the kernel, set the MAC label to .Ar label . .\" (see .\" .Xr maclabel 7 ) . .It Cm media Ar type If the driver supports the media selection system, set the media type of the interface to .Ar type . Some interfaces support the mutually exclusive use of one of several different physical media connectors. For example, a 10Mbit/s Ethernet interface might support the use of either .Tn AUI or twisted pair connectors. Setting the media type to .Cm 10base5/AUI would change the currently active connector to the AUI port. Setting it to .Cm 10baseT/UTP would activate twisted pair. Refer to the interfaces' driver specific documentation or man page for a complete list of the available types. .It Cm mediaopt Ar opts If the driver supports the media selection system, set the specified media options on the interface. The .Ar opts argument is a comma delimited list of options to apply to the interface. Refer to the interfaces' driver specific man page for a complete list of available options. .It Fl mediaopt Ar opts If the driver supports the media selection system, disable the specified media options on the interface. .It Cm mode Ar mode If the driver supports the media selection system, set the specified operating mode on the interface to .Ar mode . For IEEE 802.11 wireless interfaces that support multiple operating modes this directive is used to select between 802.11a .Pq Cm 11a , 802.11b .Pq Cm 11b , and 802.11g .Pq Cm 11g operating modes. .It Cm inst Ar minst , Cm instance Ar minst Set the media instance to .Ar minst . This is useful for devices which have multiple physical layer interfaces .Pq PHYs . .It Cm name Ar name Set the interface name to .Ar name . .It Cm rxcsum , txcsum , rxcsum6 , txcsum6 If the driver supports user-configurable checksum offloading, enable receive (or transmit) checksum offloading on the interface. The feature can be turned on selectively per protocol family. Use .Cm rxcsum6 , txcsum6 for .Xr ip6 4 or .Cm rxcsum , txcsum otherwise. Some drivers may not be able to enable these flags independently of each other, so setting one may also set the other. The driver will offload as much checksum work as it can reliably support, the exact level of offloading varies between drivers. .It Fl rxcsum , txcsum , rxcsum6 , txcsum6 If the driver supports user-configurable checksum offloading, disable receive (or transmit) checksum offloading on the interface. The feature can be turned off selectively per protocol family. Use .Fl rxcsum6 , txcsum6 for .Xr ip6 4 or .Fl rxcsum , txcsum otherwise. These settings may not always be independent of each other. .It Cm tso If the driver supports .Xr tcp 4 segmentation offloading, enable TSO on the interface. Some drivers may not be able to support TSO for .Xr ip 4 and .Xr ip6 4 packets, so they may enable only one of them. .It Fl tso If the driver supports .Xr tcp 4 segmentation offloading, disable TSO on the interface. It will always disable TSO for .Xr ip 4 and .Xr ip6 4 . .It Cm tso6 , tso4 If the driver supports .Xr tcp 4 segmentation offloading for .Xr ip6 4 or .Xr ip 4 use one of these to selectively enabled it only for one protocol family. .It Fl tso6 , tso4 If the driver supports .Xr tcp 4 segmentation offloading for .Xr ip6 4 or .Xr ip 4 use one of these to selectively disable it only for one protocol family. .It Cm lro If the driver supports .Xr tcp 4 large receive offloading, enable LRO on the interface. .It Fl lro If the driver supports .Xr tcp 4 large receive offloading, disable LRO on the interface. .It Cm wol , wol_ucast , wol_mcast , wol_magic Enable Wake On Lan (WOL) support, if available. WOL is a facility whereby a machine in a low power state may be woken in response to a received packet. There are three types of packets that may wake a system: ucast (directed solely to the machine's mac address), mcast (directed to a broadcast or multicast address), or magic (unicast or multicast frames with a ``magic contents''). Not all devices support WOL, those that do indicate the mechanisms they support in their capabilities. .Cm wol is a synonym for enabling all available WOL mechanisms. To disable WOL use .Fl wol . .It Cm vlanmtu , vlanhwtag, vlanhwfilter, vlanhwcsum, vlanhwtso If the driver offers user-configurable VLAN support, enable reception of extended frames, tag processing in hardware, frame filtering in hardware, checksum offloading, or TSO on VLAN, respectively. Note that this must be issued on a physical interface associated with .Xr vlan 4 , not on a .Xr vlan 4 interface itself. .It Fl vlanmtu , vlanhwtag, vlanhwfilter, vlanhwtso If the driver offers user-configurable VLAN support, disable reception of extended frames, tag processing in hardware, frame filtering in hardware, or TSO on VLAN, respectively. .It Cm vnet Ar jail Move the interface to the .Xr jail 8 , specified by name or JID. If the jail has a virtual network stack, the interface will disappear from the current environment and become visible to the jail. .It Fl vnet Ar jail Reclaim the interface from the .Xr jail 8 , specified by name or JID. If the jail has a virtual network stack, the interface will disappear from the jail, and become visible to the current network environment. .It Cm polling Turn on .Xr polling 4 feature and disable interrupts on the interface, if driver supports this mode. .It Fl polling Turn off .Xr polling 4 feature and enable interrupt mode on the interface. .It Cm create Create the specified network pseudo-device. If the interface is given without a unit number, try to create a new device with an arbitrary unit number. If creation of an arbitrary device is successful, the new device name is printed to standard output unless the interface is renamed or destroyed in the same .Nm invocation. .It Cm destroy Destroy the specified network pseudo-device. .It Cm plumb Another name for the .Cm create parameter. Included for .Tn Solaris compatibility. .It Cm unplumb Another name for the .Cm destroy parameter. Included for .Tn Solaris compatibility. .It Cm metric Ar n Set the routing metric of the interface to .Ar n , default 0. The routing metric is used by the routing protocol .Pq Xr routed 8 . Higher metrics have the effect of making a route less favorable; metrics are counted as additional hops to the destination network or host. .It Cm mtu Ar n Set the maximum transmission unit of the interface to .Ar n , default is interface specific. The MTU is used to limit the size of packets that are transmitted on an interface. Not all interfaces support setting the MTU, and some interfaces have range restrictions. .It Cm netmask Ar mask .\" (Inet and ISO.) (Inet only.) Specify how much of the address to reserve for subdividing networks into sub-networks. The mask includes the network part of the local address and the subnet part, which is taken from the host field of the address. The mask can be specified as a single hexadecimal number with a leading .Ql 0x , with a dot-notation Internet address, or with a pseudo-network name listed in the network table .Xr networks 5 . The mask contains 1's for the bit positions in the 32-bit address which are to be used for the network and subnet parts, and 0's for the host part. The mask should contain at least the standard network portion, and the subnet field should be contiguous with the network portion. .Pp The netmask can also be specified in CIDR notation after the address. See the .Ar address option above for more information. .It Cm prefixlen Ar len (Inet6 only.) Specify that .Ar len bits are reserved for subdividing networks into sub-networks. The .Ar len must be integer, and for syntactical reason it must be between 0 to 128. It is almost always 64 under the current IPv6 assignment rule. If the parameter is omitted, 64 is used. .Pp The prefix can also be specified using the slash notation after the address. See the .Ar address option above for more information. .It Cm remove Another name for the .Fl alias parameter. Introduced for compatibility with .Bsx . .Sm off .It Cm link Op Cm 0 No - Cm 2 .Sm on Enable special processing of the link level of the interface. These three options are interface specific in actual effect, however, they are in general used to select special modes of operation. An example of this is to enable SLIP compression, or to select the connector type for some Ethernet cards. Refer to the man page for the specific driver for more information. .Sm off .It Fl link Op Cm 0 No - Cm 2 .Sm on Disable special processing at the link level with the specified interface. .It Cm monitor Put the interface in monitor mode. No packets are transmitted, and received packets are discarded after .Xr bpf 4 processing. .It Fl monitor Take the interface out of monitor mode. .It Cm up Mark an interface .Dq up . This may be used to enable an interface after an .Dq Nm Cm down . It happens automatically when setting the first address on an interface. If the interface was reset when previously marked down, the hardware will be re-initialized. .El .Pp The following parameters are for ICMPv6 Neighbor Discovery Protocol. Note that the address family keyword .Dq Li inet6 is needed for them: .Bl -tag -width indent .It Cm accept_rtadv Set a flag to enable accepting ICMPv6 Router Advertisement messages. The .Xr sysctl 8 variable .Va net.inet6.ip6.accept_rtadv controls whether this flag is set by default or not. .It Cm -accept_rtadv Clear a flag .Cm accept_rtadv . .It Cm no_radr Set a flag to control whether routers from which the system accepts Router Advertisement messages will be added to the Default Router List or not. When the .Cm accept_rtadv flag is disabled, this flag has no effect. The .Xr sysctl 8 variable .Va net.inet6.ip6.no_radr controls whether this flag is set by default or not. .It Cm -no_radr Clear a flag .Cm no_radr . .It Cm auto_linklocal Set a flag to perform automatic link-local address configuration when the interface becomes available. The .Xr sysctl 8 variable .Va net.inet6.ip6.auto_linklocal controls whether this flag is set by default or not. .It Cm -auto_linklocal Clear a flag .Cm auto_linklocal . .It Cm defaultif Set the specified interface as the default route when there is no default router. .It Cm -defaultif Clear a flag .Cm defaultif . .It Cm ifdisabled Set a flag to disable all of IPv6 network communications on the specified interface. Note that if there are already configured IPv6 addresses on that interface, all of them are marked as .Dq tentative and DAD will be performed when this flag is cleared. .It Cm -ifdisabled Clear a flag .Cm ifdisabled . When this flag is cleared and .Cm auto_linklocal flag is enabled, automatic configuration of a link-local address is performed. .It Cm nud Set a flag to enable Neighbor Unreachability Detection. .It Cm -nud Clear a flag .Cm nud . .It Cm no_prefer_iface Set a flag to not honor rule 5 of source address selection in RFC 3484. In practice this means the address on the outgoing interface will not be preferred, effectively yielding the decision to the address selection policy table, configurable with .Xr ip6addrctl 8 . .It Cm -no_prefer_iface Clear a flag .Cm no_prefer_iface . .El .Pp The following parameters are specific for IPv6 addresses. Note that the address family keyword .Dq Li inet6 is needed for them: .Bl -tag -width indent .It Cm prefer_source Set a flag to prefer address as a candidate of the source address for outgoing packets. .It Cm -prefer_source Clear a flag .Cm prefer_source . .El .Pp The following parameters are specific to cloning IEEE 802.11 wireless interfaces with the .Cm create request: .Bl -tag -width indent .It Cm wlandev Ar device Use .Ar device as the parent for the cloned device. .It Cm wlanmode Ar mode Specify the operating mode for this cloned device. .Ar mode is one of .Cm sta , .Cm ahdemo (or .Cm adhoc-demo ), .Cm ibss , (or .Cm adhoc ), .Cm ap , (or .Cm hostap ), .Cm wds , .Cm tdma , .Cm mesh , and .Cm monitor . The operating mode of a cloned interface cannot be changed. The .Cm tdma mode is actually implemented as an .Cm adhoc-demo interface with special properties. .It Cm wlanbssid Ar bssid The 802.11 mac address to use for the bssid. This must be specified at create time for a legacy .Cm wds device. .It Cm wlanaddr Ar address The local mac address. If this is not specified then a mac address will automatically be assigned to the cloned device. Typically this address is the same as the address of the parent device but if the .Cm bssid parameter is specified then the driver will craft a unique address for the device (if supported). .It Cm wdslegacy Mark a .Cm wds device as operating in ``legacy mode''. Legacy .Cm wds devices have a fixed peer relationship and do not, for example, roam if their peer stops communicating. For completeness a Dynamic WDS (DWDS) interface may marked as .Fl wdslegacy . .It Cm bssid Request a unique local mac address for the cloned device. This is only possible if the device supports multiple mac addresses. To force use of the parent's mac address use .Fl bssid . .It Cm beacons Mark the cloned interface as depending on hardware support to track received beacons. To have beacons tracked in software use .Fl beacons . For .Cm hostap mode .Fl beacons can also be used to indicate no beacons should be transmitted; this can be useful when creating a WDS configuration but .Cm wds interfaces can only be created as companions to an access point. .El .Pp The following parameters are specific to IEEE 802.11 wireless interfaces cloned with a .Cm create operation: .Bl -tag -width indent .It Cm ampdu Enable sending and receiving AMPDU frames when using 802.11n (default). The 802.11n specification states a compliant station must be capable of receiving AMPDU frames but transmission is optional. Use .Fl ampdu to disable all use of AMPDU with 802.11n. For testing and/or to work around interoperability problems one can use .Cm ampdutx and .Cm ampdurx to control use of AMPDU in one direction. .It Cm ampdudensity Ar density Set the AMPDU density parameter used when operating with 802.11n. This parameter controls the inter-packet gap for AMPDU frames. The sending device normally controls this setting but a receiving station may request wider gaps. Legal values for .Ar density are 0, .25, .5, 1, 2, 4, 8, and 16 (microseconds). A value of .Cm - is treated the same as 0. .It Cm ampdulimit Ar limit Set the limit on packet size for receiving AMPDU frames when operating with 802.11n. Legal values for .Ar limit are 8192, 16384, 32768, and 65536 but one can also specify just the unique prefix: 8, 16, 32, 64. Note the sender may limit the size of AMPDU frames to be less than the maximum specified by the receiving station. .It Cm amsdu Enable sending and receiving AMSDU frames when using 802.11n. By default AMSDU is received but not transmitted. Use .Fl amsdu to disable all use of AMSDU with 802.11n. For testing and/or to work around interoperability problems one can use .Cm amsdutx and .Cm amsdurx to control use of AMSDU in one direction. .It Cm amsdulimit Ar limit Set the limit on packet size for sending and receiving AMSDU frames when operating with 802.11n. Legal values for .Ar limit are 7935 and 3839 (bytes). Note the sender may limit the size of AMSDU frames to be less than the maximum specified by the receiving station. Note also that devices are not required to support the 7935 limit, only 3839 is required by the specification and the larger value may require more memory to be dedicated to support functionality that is rarely used. .It Cm apbridge When operating as an access point, pass packets between wireless clients directly (default). To instead let them pass up through the system and be forwarded using some other mechanism, use .Fl apbridge . Disabling the internal bridging is useful when traffic is to be processed with packet filtering. .It Cm authmode Ar mode Set the desired authentication mode in infrastructure mode. Not all adapters support all modes. The set of valid modes is .Cm none , open , shared (shared key), .Cm 8021x (IEEE 802.1x), and .Cm wpa (IEEE WPA/WPA2/802.11i). The .Cm 8021x and .Cm wpa modes are only useful when using an authentication service (a supplicant for client operation or an authenticator when operating as an access point). Modes are case insensitive. .It Cm bgscan Enable background scanning when operating as a station. Background scanning is a technique whereby a station associated to an access point will temporarily leave the channel to scan for neighboring stations. This allows a station to maintain a cache of nearby access points so that roaming between access points can be done without a lengthy scan operation. Background scanning is done only when a station is not busy and any outbound traffic will cancel a scan operation. Background scanning should never cause packets to be lost though there may be some small latency if outbound traffic interrupts a scan operation. By default background scanning is enabled if the device is capable. To disable background scanning, use .Fl bgscan . Background scanning is controlled by the .Cm bgscanidle and .Cm bgscanintvl parameters. Background scanning must be enabled for roaming; this is an artifact of the current implementation and may not be required in the future. .It Cm bgscanidle Ar idletime Set the minimum time a station must be idle (not transmitting or receiving frames) before a background scan is initiated. The .Ar idletime parameter is specified in milliseconds. By default a station must be idle at least 250 milliseconds before a background scan is initiated. The idle time may not be set to less than 100 milliseconds. .It Cm bgscanintvl Ar interval Set the interval at which background scanning is attempted. The .Ar interval parameter is specified in seconds. By default a background scan is considered every 300 seconds (5 minutes). The .Ar interval may not be set to less than 15 seconds. .It Cm bintval Ar interval Set the interval at which beacon frames are sent when operating in ad-hoc or ap mode. The .Ar interval parameter is specified in TU's (1024 usecs). By default beacon frames are transmitted every 100 TU's. .It Cm bmissthreshold Ar count Set the number of consecutive missed beacons at which the station will attempt to roam (i.e., search for a new access point). The .Ar count parameter must be in the range 1 to 255; though the upper bound may be reduced according to device capabilities. The default threshold is 7 consecutive missed beacons; but this may be overridden by the device driver. Another name for the .Cm bmissthreshold parameter is .Cm bmiss . .It Cm bssid Ar address Specify the MAC address of the access point to use when operating as a station in a BSS network. This overrides any automatic selection done by the system. To disable a previously selected access point, supply .Cm any , none , or .Cm - for the address. This option is useful when more than one access point uses the same SSID. Another name for the .Cm bssid parameter is .Cm ap . .It Cm burst Enable packet bursting. Packet bursting is a transmission technique whereby the wireless medium is acquired once to send multiple frames and the interframe spacing is reduced. This technique can significantly increase throughput by reducing transmission overhead. Packet bursting is supported by the 802.11e QoS specification and some devices that do not support QoS may still be capable. By default packet bursting is enabled if a device is capable of doing it. To disable packet bursting, use .Fl burst . .It Cm chanlist Ar channels Set the desired channels to use when scanning for access points, neighbors in an IBSS network, or looking for unoccupied channels when operating as an access point. The set of channels is specified as a comma-separated list with each element in the list representing either a single channel number or a range of the form .Dq Li a-b . Channel numbers must be in the range 1 to 255 and be permissible according to the operating characteristics of the device. .It Cm channel Ar number Set a single desired channel. Channels range from 1 to 255, but the exact selection available depends on the region your adaptor was manufactured for. Setting the channel to .Li any , or .Cm - will clear any desired channel and, if the device is marked up, force a scan for a channel to operate on. Alternatively the frequency, in megahertz, may be specified instead of the channel number. .Pp When there are several ways to use a channel the channel number/frequency may be appended with attributes to clarify. For example, if a device is capable of operating on channel 6 with 802.11n and 802.11g then one can specify that g-only use should be used by specifying ``6:g''. Similarly the channel width can be specified by appending it with ``/''; e.g., ``6/40'' specifies a 40MHz wide channel, These attributes can be combined as in: ``6:ht/40''. The full set of flags specified following a ``:'' are: .Cm a (802.11a), .Cm b (802.11b), .Cm d (Atheros Dynamic Turbo mode), .Cm g (802.11g), .Cm h or .Cm n (802.11n aka HT), .Cm s (Atheros Static Turbo mode), and .Cm t (Atheros Dynamic Turbo mode, or appended to ``st'' and ``dt''). The full set of channel widths following a '/' are: .Cm 5 (5MHz aka quarter-rate channel), .Cm 10 (10MHz aka half-rate channel), .Cm 20 (20MHz mostly for use in specifying ht20), and .Cm 40 (40MHz mostly for use in specifying ht40). In addition, a 40MHz HT channel specification may include the location of the extension channel by appending ``+'' or ``-'' for above and below, respectively; e.g., ``2437:ht/40+'' specifies 40MHz wide HT operation with the center channel at frequency 2437 and the extension channel above. .It Cm country Ar name Set the country code to use in calculating the regulatory constraints for operation. In particular the set of available channels, how the wireless device will operation on the channels, and the maximum transmit power that can be used on a channel are defined by this setting. Country/Region codes are specified as a 2-character abbreviation defined by ISO 3166 or using a longer, but possibly ambiguous, spelling; e.g., "ES" and "Spain". The set of country codes are taken from .Pa /etc/regdomain.xml and can also be viewed with the ``list countries'' request. Note that not all devices support changing the country code from a default setting; typically stored in EEPROM. See also .Cm regdomain , .Cm indoor , .Cm outdoor , and .Cm anywhere . .It Cm dfs Enable Dynamic Frequency Selection (DFS) as specified in 802.11h. DFS embodies several facilities including detection of overlapping radar signals, dynamic transmit power control, and channel selection according to a least-congested criteria. DFS support is mandatory for some 5GHz frequencies in certain locales (e.g., ETSI). By default DFS is enabled according to the regulatory definitions specified in .Pa /etc/regdomain.xml and the current country code, regdomain, and channel. Note the underlying device (and driver) must support radar detection for full DFS support to work. To be fully compliant with the local regulatory agency frequencies that require DFS should not be used unless it is fully supported. Use .Fl dfs to disable this functionality for testing. .It Cm dotd Enable support for the 802.11d specification (default). When this support is enabled in station mode, beacon frames that advertise a country code different than the currently configured country code will cause an event to be dispatched to user applications. This event can be used by the station to adopt that country code and operate according to the associated regulatory constraints. When operating as an access point with 802.11d enabled the beacon and probe response frames transmitted will advertise the current regulatory domain settings. To disable 802.11d use .Fl dotd . .It Cm doth Enable 802.11h support including spectrum management. When 802.11h is enabled beacon and probe response frames will have the SpectrumMgt bit set in the capabilities field and country and power constraint information elements will be present. 802.11h support also includes handling Channel Switch Announcements (CSA) which are a mechanism to coordinate channel changes by an access point. By default 802.11h is enabled if the device is capable. To disable 802.11h use .Fl doth . .It Cm deftxkey Ar index Set the default key to use for transmission. Typically this is only set when using WEP encryption. Note that you must set a default transmit key for the system to know which key to use in encrypting outbound traffic. The .Cm weptxkey is an alias for this request; it is provided for backwards compatibility. .It Cm dtimperiod Ar period Set the DTIM period for transmitting buffered multicast data frames when operating in ap mode. The .Ar period specifies the number of beacon intervals between DTIM and must be in the range 1 to 15. By default DTIM is 1 (i.e., DTIM occurs at each beacon). .It Cm quiet Enable the use of quiet IE. Hostap will use this to silence other stations to reduce interference for radar detection when operating on 5GHz frequency and doth support is enabled. Use .Fl quiet to disable this functionality. .It Cm quiet_period Ar period Set the QUIET .Ar period to the number of beacon intervals between the start of regularly scheduled quiet intervals defined by Quiet element. .It Cm quiet_count Ar count Set the QUIET .Ar count to the number of TBTTs until the beacon interval during which the next quiet interval shall start. A value of 1 indicates the quiet interval will start during the beacon interval starting at the next TBTT. A value 0 is reserved. .It Cm quiet_offset Ar offset Set the QUIET .Ar offset to the offset of the start of the quiet interval from the TBTT specified by the Quiet count, expressed in TUs. The value of the .Ar offset shall be less than one beacon interval. .It Cm quiet_duration Ar dur Set the QUIET .Ar dur to the duration of the Quiet interval, expressed in TUs. The value should be less than beacon interval. .It Cm dturbo Enable the use of Atheros Dynamic Turbo mode when communicating with another Dynamic Turbo-capable station. Dynamic Turbo mode is an Atheros-specific mechanism by which stations switch between normal 802.11 operation and a ``boosted'' mode in which a 40MHz wide channel is used for communication. Stations using Dynamic Turbo mode operate boosted only when the channel is free of non-dturbo stations; when a non-dturbo station is identified on the channel all stations will automatically drop back to normal operation. By default, Dynamic Turbo mode is not enabled, even if the device is capable. Note that turbo mode (dynamic or static) is only allowed on some channels depending on the regulatory constraints; use the .Cm list chan command to identify the channels where turbo mode may be used. To disable Dynamic Turbo mode use .Fl dturbo . .It Cm dwds Enable Dynamic WDS (DWDS) support. DWDS is a facility by which 4-address traffic can be carried between stations operating in infrastructure mode. A station first associates to an access point and authenticates using normal procedures (e.g., WPA). Then 4-address frames are passed to carry traffic for stations operating on either side of the wireless link. DWDS extends the normal WDS mechanism by leveraging existing security protocols and eliminating static binding. .Pp When DWDS is enabled on an access point 4-address frames received from an authorized station will generate a ``DWDS discovery'' event to user applications. This event should be used to create a WDS interface that is bound to the remote station (and usually plumbed into a bridge). Once the WDS interface is up and running 4-address traffic then logically flows through that interface. .Pp When DWDS is enabled on a station, traffic with a destination address different from the peer station are encapsulated in a 4-address frame and transmitted to the peer. All 4-address traffic uses the security information of the stations (e.g., cryptographic keys). A station is associated using 802.11n facilities may transport 4-address traffic using these same mechanisms; this depends on available resources and capabilities of the device. The DWDS implementation guards against layer 2 routing loops of multicast traffic. .It Cm ff Enable the use of Atheros Fast Frames when communicating with another Fast Frames-capable station. Fast Frames are an encapsulation technique by which two 802.3 frames are transmitted in a single 802.11 frame. This can noticeably improve throughput but requires that the receiving station understand how to decapsulate the frame. Fast frame use is negotiated using the Atheros 802.11 vendor-specific protocol extension so enabling use is safe when communicating with non-Atheros devices. By default, use of fast frames is enabled if the device is capable. To explicitly disable fast frames, use .Fl ff . .It Cm fragthreshold Ar length Set the threshold for which transmitted frames are broken into fragments. The .Ar length argument is the frame size in bytes and must be in the range 256 to 2346. Setting .Ar length to .Li 2346 , .Cm any , or .Cm - disables transmit fragmentation. Not all adapters honor the fragmentation threshold. .It Cm hidessid When operating as an access point, do not broadcast the SSID in beacon frames or respond to probe request frames unless they are directed to the ap (i.e., they include the ap's SSID). By default, the SSID is included in beacon frames and undirected probe request frames are answered. To re-enable the broadcast of the SSID etc., use .Fl hidessid . .It Cm ht Enable use of High Throughput (HT) when using 802.11n (default). The 802.11n specification includes mechanisms for operation on 20MHz and 40MHz wide channels using different signalling mechanisms than specified in 802.11b, 802.11g, and 802.11a. Stations negotiate use of these facilities, termed HT20 and HT40, when they associate. To disable all use of 802.11n use .Fl ht . To disable use of HT20 (e.g., to force only HT40 use) use .Fl ht20 . To disable use of HT40 use .Fl ht40 . .Pp HT configuration is used to ``auto promote'' operation when several choices are available. For example, if a station associates to an 11n-capable access point it controls whether the station uses legacy operation, HT20, or HT40. When an 11n-capable device is setup as an access point and Auto Channel Selection is used to locate a channel to operate on, HT configuration controls whether legacy, HT20, or HT40 operation is setup on the selected channel. If a fixed channel is specified for a station then HT configuration can be given as part of the channel specification; e.g., 6:ht/20 to setup HT20 operation on channel 6. .It Cm htcompat Enable use of compatibility support for pre-802.11n devices (default). The 802.11n protocol specification went through several incompatible iterations. Some vendors implemented 11n support to older specifications that will not interoperate with a purely 11n-compliant station. In particular the information elements included in management frames for old devices are different. When compatibility support is enabled both standard and compatible data will be provided. Stations that associate using the compatibility mechanisms are flagged in ``list sta''. To disable compatibility support use .Fl htcompat . .It Cm htprotmode Ar technique For interfaces operating in 802.11n, use the specified .Ar technique for protecting HT frames in a mixed legacy/HT network. The set of valid techniques is .Cm off , and .Cm rts (RTS/CTS, default). Technique names are case insensitive. .It Cm inact Enable inactivity processing for stations associated to an access point (default). When operating as an access point the 802.11 layer monitors the activity of each associated station. When a station is inactive for 5 minutes it will send several ``probe frames'' to see if the station is still present. If no response is received then the station is deauthenticated. Applications that prefer to handle this work can disable this facility by using .Fl inact . .It Cm indoor Set the location to use in calculating regulatory constraints. The location is also advertised in beacon and probe response frames when 802.11d is enabled with .Cm dotd . See also .Cm outdoor , .Cm anywhere , .Cm country , and .Cm regdomain . .It Cm list active Display the list of channels available for use taking into account any restrictions set with the .Cm chanlist directive. See the description of .Cm list chan for more information. .It Cm list caps Display the adaptor's capabilities, including the operating modes supported. .It Cm list chan Display the list of channels available for use. Channels are shown with their IEEE channel number, equivalent frequency, and usage modes. Channels identified as .Ql 11g are also usable in .Ql 11b mode. Channels identified as .Ql 11a Turbo may be used only for Atheros' Static Turbo mode (specified with . Cm mediaopt turbo ) . Channels marked with a .Ql * have a regulatory constraint that they be passively scanned. This means a station is not permitted to transmit on the channel until it identifies the channel is being used for 802.11 communication; typically by hearing a beacon frame from an access point operating on the channel. .Cm list freq is another way of requesting this information. By default a compacted list of channels is displayed; if the .Fl v option is specified then all channels are shown. .It Cm list countries Display the set of country codes and regulatory domains that can be used in regulatory configuration. .It Cm list mac Display the current MAC Access Control List state. Each address is prefixed with a character that indicates the current policy applied to it: .Ql + indicates the address is allowed access, .Ql - indicates the address is denied access, .Ql * indicates the address is present but the current policy open (so the ACL is not consulted). .It Cm list mesh Displays the mesh routing table, used for forwarding packets on a mesh network. .It Cm list regdomain Display the current regulatory settings including the available channels and transmit power caps. .It Cm list roam Display the parameters that govern roaming operation. .It Cm list txparam Display the parameters that govern transmit operation. .It Cm list txpower Display the transmit power caps for each channel. .It Cm list scan Display the access points and/or ad-hoc neighbors located in the vicinity. This information may be updated automatically by the adapter with a .Cm scan request or through background scanning. Depending on the capabilities of the stations the following flags can be included in the output: .Bl -tag -width 3n .It Li A Authorized. Indicates that the station is permitted to send/receive data frames. .It Li E Extended Rate Phy (ERP). Indicates that the station is operating in an 802.11g network using extended transmit rates. .It Li H High Throughput (HT). Indicates that the station is using HT transmit rates. If a `+' follows immediately after then the station associated using deprecated mechanisms supported only when .Cm htcompat is enabled. .It Li P Power Save. Indicates that the station is operating in power save mode. .It Li Q Quality of Service (QoS). Indicates that the station is using QoS encapsulation for data frame. QoS encapsulation is enabled only when WME mode is enabled. .It Li S Short Preamble. Indicates that the station is doing short preamble to optionally improve throughput performance with 802.11g and 802.11b. .It Li T Transitional Security Network (TSN). Indicates that the station associated using TSN; see also .Cm tsn below. .It Li W Wi-Fi Protected Setup (WPS). Indicates that the station associated using WPS. .El .Pp By default interesting information elements captured from the neighboring stations are displayed at the end of each row. Possible elements include: .Cm WME (station supports WME), .Cm WPA (station supports WPA), .Cm WPS (station supports WPS), .Cm RSN (station supports 802.11i/RSN), .Cm HTCAP (station supports 802.11n/HT communication), .Cm ATH (station supports Atheros protocol extensions), .Cm VEN (station supports unknown vendor-specific extensions). If the .Fl v flag is used all the information elements and their contents will be shown. Specifying the .Fl v flag also enables display of long SSIDs. The .Cm list ap command is another way of requesting this information. .It Cm list sta When operating as an access point display the stations that are currently associated. When operating in ad-hoc mode display stations identified as neighbors in the IBSS. When operating in mesh mode display stations identified as neighbors in the MBSS. When operating in station mode display the access point. Capabilities advertised by the stations are described under the .Cm scan request. Depending on the capabilities of the stations the following flags can be included in the output: .Bl -tag -width 3n .It Li A Authorized. Indicates that the station is permitted to send/receive data frames. .It Li E Extended Rate Phy (ERP). Indicates that the station is operating in an 802.11g network using extended transmit rates. .It Li H High Throughput (HT). Indicates that the station is using HT transmit rates. If a `+' follows immediately after then the station associated using deprecated mechanisms supported only when .Cm htcompat is enabled. .It Li P Power Save. Indicates that the station is operating in power save mode. .It Li Q Quality of Service (QoS). Indicates that the station is using QoS encapsulation for data frame. QoS encapsulation is enabled only when WME mode is enabled. .It Li S Short Preamble. Indicates that the station is doing short preamble to optionally improve throughput performance with 802.11g and 802.11b. .It Li T Transitional Security Network (TSN). Indicates that the station associated using TSN; see also .Cm tsn below. .It Li W Wi-Fi Protected Setup (WPS). Indicates that the station associated using WPS. .El .Pp By default information elements received from associated stations are displayed in a short form; the .Fl v flag causes this information to be displayed symbolically. .It Cm list wme Display the current channel parameters to use when operating in WME mode. If the .Fl v option is specified then both channel and BSS parameters are displayed for each AC (first channel, then BSS). When WME mode is enabled for an adaptor this information will be displayed with the regular status; this command is mostly useful for examining parameters when WME mode is disabled. See the description of the .Cm wme directive for information on the various parameters. .It Cm maxretry Ar count Set the maximum number of tries to use in sending unicast frames. The default setting is 6 but drivers may override this with a value they choose. .It Cm mcastrate Ar rate Set the rate for transmitting multicast/broadcast frames. Rates are specified as megabits/second in decimal; e.g.,\& 5.5 for 5.5 Mb/s. This rate should be valid for the current operating conditions; if an invalid rate is specified drivers are free to chose an appropriate rate. .It Cm mgtrate Ar rate Set the rate for transmitting management and/or control frames. Rates are specified as megabits/second in decimal; e.g.,\& 5.5 for 5.5 Mb/s. .It Cm outdoor Set the location to use in calculating regulatory constraints. The location is also advertised in beacon and probe response frames when 802.11d is enabled with .Cm dotd . See also .Cm anywhere , .Cm country , .Cm indoor , and .Cm regdomain . .It Cm powersave Enable powersave operation. When operating as a client, the station will conserve power by periodically turning off the radio and listening for messages from the access point telling it there are packets waiting. The station must then retrieve the packets. Not all devices support power save operation as a client. The 802.11 specification requires that all access points support power save but some drivers do not. Use .Fl powersave to disable powersave operation when operating as a client. .It Cm powersavesleep Ar sleep Set the desired max powersave sleep time in TU's (1024 usecs). By default the max powersave sleep time is 100 TU's. .It Cm protmode Ar technique For interfaces operating in 802.11g, use the specified .Ar technique for protecting OFDM frames in a mixed 11b/11g network. The set of valid techniques is .Cm off , cts (CTS to self), and .Cm rtscts (RTS/CTS). Technique names are case insensitive. Not all devices support .Cm cts as a protection technique. .It Cm pureg When operating as an access point in 802.11g mode allow only 11g-capable stations to associate (11b-only stations are not permitted to associate). To allow both 11g and 11b-only stations to associate, use .Fl pureg . .It Cm puren When operating as an access point in 802.11n mode allow only HT-capable stations to associate (legacy stations are not permitted to associate). To allow both HT and legacy stations to associate, use .Fl puren . .It Cm regdomain Ar sku Set the regulatory domain to use in calculating the regulatory constraints for operation. In particular the set of available channels, how the wireless device will operation on the channels, and the maximum transmit power that can be used on a channel are defined by this setting. Regdomain codes (SKU's) are taken from .Pa /etc/regdomain.xml and can also be viewed with the ``list countries'' request. Note that not all devices support changing the regdomain from a default setting; typically stored in EEPROM. See also .Cm country , .Cm indoor , .Cm outdoor , and .Cm anywhere . .It Cm rifs Enable use of Reduced InterFrame Spacing (RIFS) when operating in 802.11n on an HT channel. Note that RIFS must be supported by both the station and access point for it to be used. To disable RIFS use .Fl rifs . .It Cm roam:rate Ar rate Set the threshold for controlling roaming when operating in a BSS. The .Ar rate parameter specifies the transmit rate in megabits at which roaming should be considered. If the current transmit rate drops below this setting and background scanning is enabled, then the system will check if a more desirable access point is available and switch over to it. The current scan cache contents are used if they are considered valid according to the .Cm scanvalid parameter; otherwise a background scan operation is triggered before any selection occurs. Each channel type has a separate rate threshold; the default values are: 12 Mb/s (11a), 2 Mb/s (11b), 2 Mb/s (11g), MCS 1 (11na, 11ng). .It Cm roam:rssi Ar rssi Set the threshold for controlling roaming when operating in a BSS. The .Ar rssi parameter specifies the receive signal strength in dBm units at which roaming should be considered. If the current rssi drops below this setting and background scanning is enabled, then the system will check if a more desirable access point is available and switch over to it. The current scan cache contents are used if they are considered valid according to the .Cm scanvalid parameter; otherwise a background scan operation is triggered before any selection occurs. Each channel type has a separate rssi threshold; the default values are all 7 dBm. .It Cm roaming Ar mode When operating as a station, control how the system will behave when communication with the current access point is broken. The .Ar mode argument may be one of .Cm device (leave it to the hardware device to decide), .Cm auto (handle either in the device or the operating system\[em]as appropriate), .Cm manual (do nothing until explicitly instructed). By default, the device is left to handle this if it is capable; otherwise, the operating system will automatically attempt to reestablish communication. Manual mode is used by applications such as .Xr wpa_supplicant 8 that want to control the selection of an access point. .It Cm rtsthreshold Ar length Set the threshold for which transmitted frames are preceded by transmission of an RTS control frame. The .Ar length argument is the frame size in bytes and must be in the range 1 to 2346. Setting .Ar length to .Li 2346 , .Cm any , or .Cm - disables transmission of RTS frames. Not all adapters support setting the RTS threshold. .It Cm scan Initiate a scan of neighboring stations, wait for it to complete, and display all stations found. Only the super-user can initiate a scan. See .Cm list scan for information on the display. By default a background scan is done; otherwise a foreground scan is done and the station may roam to a different access point. The .Cm list scan request can be used to show recent scan results without initiating a new scan. .It Cm scanvalid Ar threshold Set the maximum time the scan cache contents are considered valid; i.e., will be used without first triggering a scan operation to refresh the data. The .Ar threshold parameter is specified in seconds and defaults to 60 seconds. The minimum setting for .Ar threshold is 10 seconds. One should take care setting this threshold; if it is set too low then attempts to roam to another access point may trigger unnecessary background scan operations. .It Cm shortgi Enable use of Short Guard Interval when operating in 802.11n on an HT channel. NB: this currently enables Short GI on both HT40 and HT20 channels. To disable Short GI use .Fl shortgi . .It Cm smps Enable use of Static Spatial Multiplexing Power Save (SMPS) when operating in 802.11n. A station operating with Static SMPS maintains only a single receive chain active (this can significantly reduce power consumption). To disable SMPS use .Fl smps . .It Cm smpsdyn Enable use of Dynamic Spatial Multiplexing Power Save (SMPS) when operating in 802.11n. A station operating with Dynamic SMPS maintains only a single receive chain active but switches to multiple receive chains when it receives an RTS frame (this can significantly reduce power consumption). Note that stations cannot distinguish between RTS/CTS intended to enable multiple receive chains and those used for other purposes. To disable SMPS use .Fl smps . .It Cm ssid Ar ssid Set the desired Service Set Identifier (aka network name). The SSID is a string up to 32 characters in length and may be specified as either a normal string or in hexadecimal when preceded by .Ql 0x . Additionally, the SSID may be cleared by setting it to .Ql - . .It Cm tdmaslot Ar slot When operating with TDMA, use the specified .Ar slot configuration. The .Ar slot is a number between 0 and the maximum number of slots in the BSS. Note that a station configured as slot 0 is a master and will broadcast beacon frames advertising the BSS; stations configured to use other slots will always scan to locate a master before they ever transmit. By default .Cm tdmaslot is set to 1. .It Cm tdmaslotcnt Ar cnt When operating with TDMA, setup a BSS with .Ar cnt slots. The slot count may be at most 8. The current implementation is only tested with two stations (i.e., point to point applications). This setting is only meaningful when a station is configured as slot 0; other stations adopt this setting from the BSS they join. By default .Cm tdmaslotcnt is set to 2. .It Cm tdmaslotlen Ar len When operating with TDMA, setup a BSS such that each station has a slot .Ar len microseconds long. The slot length must be at least 150 microseconds (1/8 TU) and no more than 65 milliseconds. Note that setting too small a slot length may result in poor channel bandwidth utilization due to factors such as timer granularity and guard time. This setting is only meaningful when a station is configured as slot 0; other stations adopt this setting from the BSS they join. By default .Cm tdmaslotlen is set to 10 milliseconds. .It Cm tdmabintval Ar intval When operating with TDMA, setup a BSS such that beacons are transmitted every .Ar intval superframes to synchronize the TDMA slot timing. A superframe is defined as the number of slots times the slot length; e.g., a BSS with two slots of 10 milliseconds has a 20 millisecond superframe. The beacon interval may not be zero. A lower setting of .Cm tdmabintval causes the timers to be resynchronized more often; this can be help if significant timer drift is observed. By default .Cm tdmabintval is set to 5. .It Cm tsn When operating as an access point with WPA/802.11i allow legacy stations to associate using static key WEP and open authentication. To disallow legacy station use of WEP, use .Fl tsn . .It Cm txpower Ar power Set the power used to transmit frames. The .Ar power argument is specified in .5 dBm units. Out of range values are truncated. Typically only a few discreet power settings are available and the driver will use the setting closest to the specified value. Not all adapters support changing the transmit power. .It Cm ucastrate Ar rate Set a fixed rate for transmitting unicast frames. Rates are specified as megabits/second in decimal; e.g.,\& 5.5 for 5.5 Mb/s. This rate should be valid for the current operating conditions; if an invalid rate is specified drivers are free to chose an appropriate rate. .It Cm wepmode Ar mode Set the desired WEP mode. Not all adapters support all modes. The set of valid modes is .Cm off , on , and .Cm mixed . The .Cm mixed mode explicitly tells the adaptor to allow association with access points which allow both encrypted and unencrypted traffic. On these adapters, .Cm on means that the access point must only allow encrypted connections. On other adapters, .Cm on is generally another name for .Cm mixed . Modes are case insensitive. .It Cm weptxkey Ar index Set the WEP key to be used for transmission. This is the same as setting the default transmission key with .Cm deftxkey . .It Cm wepkey Ar key Ns | Ns Ar index : Ns Ar key Set the selected WEP key. If an .Ar index is not given, key 1 is set. A WEP key will be either 5 or 13 characters (40 or 104 bits) depending on the local network and the capabilities of the adaptor. It may be specified either as a plain string or as a string of hexadecimal digits preceded by .Ql 0x . For maximum portability, hex keys are recommended; the mapping of text keys to WEP encryption is usually driver-specific. In particular, the .Tn Windows drivers do this mapping differently to .Fx . A key may be cleared by setting it to .Ql - . If WEP is supported then there are at least four keys. Some adapters support more than four keys. If that is the case, then the first four keys (1-4) will be the standard temporary keys and any others will be adaptor specific keys such as permanent keys stored in NVRAM. .Pp Note that you must set a default transmit key with .Cm deftxkey for the system to know which key to use in encrypting outbound traffic. .It Cm wme Enable Wireless Multimedia Extensions (WME) support, if available, for the specified interface. WME is a subset of the IEEE 802.11e standard to support the efficient communication of realtime and multimedia data. To disable WME support, use .Fl wme . Another name for this parameter is .Cm wmm . .Pp The following parameters are meaningful only when WME support is in use. Parameters are specified per-AC (Access Category) and split into those that are used by a station when acting as an access point and those for client stations in the BSS. The latter are received from the access point and may not be changed (at the station). The following Access Categories are recognized: .Pp .Bl -tag -width ".Cm AC_BK" -compact .It Cm AC_BE (or .Cm BE ) best effort delivery, .It Cm AC_BK (or .Cm BK ) background traffic, .It Cm AC_VI (or .Cm VI ) video traffic, .It Cm AC_VO (or .Cm VO ) voice traffic. .El .Pp AC parameters are case-insensitive. Traffic classification is done in the operating system using the vlan priority associated with data frames or the ToS (Type of Service) indication in IP-encapsulated frames. If neither information is present, traffic is assigned to the Best Effort (BE) category. .Bl -tag -width indent .It Cm ack Ar ac Set the ACK policy for QoS transmissions by the local station; this controls whether or not data frames transmitted by a station require an ACK response from the receiving station. To disable waiting for an ACK use .Fl ack . This parameter is applied only to the local station. .It Cm acm Ar ac Enable the Admission Control Mandatory (ACM) mechanism for transmissions by the local station. To disable the ACM use .Fl acm . On stations in a BSS this parameter is read-only and indicates the setting received from the access point. NB: ACM is not supported right now. .It Cm aifs Ar ac Ar count Set the Arbitration Inter Frame Spacing (AIFS) channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm cwmin Ar ac Ar count Set the CWmin channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm cwmax Ar ac Ar count Set the CWmax channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm txoplimit Ar ac Ar limit Set the Transmission Opportunity Limit channel access parameter to use for transmissions by the local station. This parameter defines an interval of time when a WME station has the right to initiate transmissions onto the wireless medium. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm bss:aifs Ar ac Ar count Set the AIFS channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:cwmin Ar ac Ar count Set the CWmin channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:cwmax Ar ac Ar count Set the CWmax channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:txoplimit Ar ac Ar limit Set the TxOpLimit channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .El .It Cm wps Enable Wireless Privacy Subscriber support. Note that WPS support requires a WPS-capable supplicant. To disable this function use .Fl wps . .El .Pp The following parameters support an optional access control list feature available with some adapters when operating in ap mode; see .Xr wlan_acl 4 . This facility allows an access point to accept/deny association requests based on the MAC address of the station. Note that this feature does not significantly enhance security as MAC address spoofing is easy to do. .Bl -tag -width indent .It Cm mac:add Ar address Add the specified MAC address to the database. Depending on the policy setting association requests from the specified station will be allowed or denied. .It Cm mac:allow Set the ACL policy to permit association only by stations registered in the database. .It Cm mac:del Ar address Delete the specified MAC address from the database. .It Cm mac:deny Set the ACL policy to deny association only by stations registered in the database. .It Cm mac:kick Ar address Force the specified station to be deauthenticated. This typically is done to block a station after updating the address database. .It Cm mac:open Set the ACL policy to allow all stations to associate. .It Cm mac:flush Delete all entries in the database. .It Cm mac:radius Set the ACL policy to permit association only by stations approved by a RADIUS server. Note that this feature requires the .Xr hostapd 8 program be configured to do the right thing as it handles the RADIUS processing (and marks stations as authorized). .El .Pp The following parameters are related to a wireless interface operating in mesh mode: .Bl -tag -width indent .It Cm meshid Ar meshid Set the desired Mesh Identifier. The Mesh ID is a string up to 32 characters in length. A mesh interface must have a Mesh Identifier specified to reach an operational state. .It Cm meshttl Ar ttl Set the desired ``time to live'' for mesh forwarded packets; this is the number of hops a packet may be forwarded before it is discarded. The default setting for .Cm meshttl is 31. .It Cm meshpeering Enable or disable peering with neighbor mesh stations. Stations must peer before any data packets can be exchanged. By default .Cm meshpeering is enabled. .It Cm meshforward Enable or disable forwarding packets by a mesh interface. By default .Cm meshforward is enabled. .It Cm meshgate This attribute specifies whether or not the mesh STA activates mesh gate announcements. By default .Cm meshgate is disabled. .It Cm meshmetric Ar protocol Set the specified .Ar protocol as the link metric protocol used on a mesh network. The default protocol is called .Ar AIRTIME . The mesh interface will restart after changing this setting. .It Cm meshpath Ar protocol Set the specified .Ar protocol as the path selection protocol used on a mesh network. The only available protocol at the moment is called .Ar HWMP (Hybrid Wireless Mesh Protocol). The mesh interface will restart after changing this setting. .It Cm hwmprootmode Ar mode Stations on a mesh network can operate as ``root nodes.'' Root nodes try to find paths to all mesh nodes and advertise themselves regularly. When there is a root mesh node on a network, other mesh nodes can setup paths between themselves faster because they can use the root node to find the destination. This path may not be the best, but on-demand routing will eventually find the best path. The following modes are recognized: .Pp .Bl -tag -width ".Cm PROACTIVE" -compact .It Cm DISABLED Disable root mode. .It Cm NORMAL Send broadcast path requests every two seconds. Nodes on the mesh without a path to this root mesh station with try to discover a path to us. .It Cm PROACTIVE Send broadcast path requests every two seconds and every node must reply with a path reply even if it already has a path to this root mesh station. .It Cm RANN Send broadcast root announcement (RANN) frames. Nodes on the mesh without a path to this root mesh station with try to discover a path to us. .El By default .Cm hwmprootmode is set to .Ar DISABLED . .It Cm hwmpmaxhops Ar cnt Set the maximum number of hops allowed in an HMWP path to .Ar cnt . The default setting for .Cm hwmpmaxhops is 31. .El .Pp The following parameters are for compatibility with other systems: .Bl -tag -width indent .It Cm nwid Ar ssid Another name for the .Cm ssid parameter. Included for .Nx compatibility. .It Cm stationname Ar name Set the name of this station. The station name is not part of the IEEE 802.11 protocol though some interfaces support it. As such it only seems to be meaningful to identical or virtually identical equipment. Setting the station name is identical in syntax to setting the SSID. One can also use .Cm station for .Bsx compatibility. .It Cm wep Another way of saying .Cm wepmode on . Included for .Bsx compatibility. .It Fl wep Another way of saying .Cm wepmode off . Included for .Bsx compatibility. .It Cm nwkey key Another way of saying: .Dq Li "wepmode on weptxkey 1 wepkey 1:key wepkey 2:- wepkey 3:- wepkey 4:-" . Included for .Nx compatibility. .It Cm nwkey Xo .Sm off .Ar n : k1 , k2 , k3 , k4 .Sm on .Xc Another way of saying .Dq Li "wepmode on weptxkey n wepkey 1:k1 wepkey 2:k2 wepkey 3:k3 wepkey 4:k4" . Included for .Nx compatibility. .It Fl nwkey Another way of saying .Cm wepmode off . Included for .Nx compatibility. .El .Pp The following parameters are specific to bridge interfaces: .Bl -tag -width indent .It Cm addm Ar interface Add the interface named by .Ar interface as a member of the bridge. The interface is put into promiscuous mode so that it can receive every packet sent on the network. .It Cm deletem Ar interface Remove the interface named by .Ar interface from the bridge. Promiscuous mode is disabled on the interface when it is removed from the bridge. .It Cm maxaddr Ar size Set the size of the bridge address cache to .Ar size . The default is 2000 entries. .It Cm timeout Ar seconds Set the timeout of address cache entries to .Ar seconds seconds. If .Ar seconds is zero, then address cache entries will not be expired. The default is 1200 seconds. .It Cm addr Display the addresses that have been learned by the bridge. .It Cm static Ar interface-name Ar address Add a static entry into the address cache pointing to .Ar interface-name . Static entries are never aged out of the cache or re-placed, even if the address is seen on a different interface. .It Cm deladdr Ar address Delete .Ar address from the address cache. .It Cm flush Delete all dynamically-learned addresses from the address cache. .It Cm flushall Delete all addresses, including static addresses, from the address cache. .It Cm discover Ar interface Mark an interface as a .Dq discovering interface. When the bridge has no address cache entry (either dynamic or static) for the destination address of a packet, the bridge will forward the packet to all member interfaces marked as .Dq discovering . This is the default for all interfaces added to a bridge. .It Cm -discover Ar interface Clear the .Dq discovering attribute on a member interface. For packets without the .Dq discovering attribute, the only packets forwarded on the interface are broadcast or multicast packets and packets for which the destination address is known to be on the interface's segment. .It Cm learn Ar interface Mark an interface as a .Dq learning interface. When a packet arrives on such an interface, the source address of the packet is entered into the address cache as being a destination address on the interface's segment. This is the default for all interfaces added to a bridge. .It Cm -learn Ar interface Clear the .Dq learning attribute on a member interface. .It Cm sticky Ar interface Mark an interface as a .Dq sticky interface. Dynamically learned address entries are treated at static once entered into the cache. Sticky entries are never aged out of the cache or replaced, even if the address is seen on a different interface. .It Cm -sticky Ar interface Clear the .Dq sticky attribute on a member interface. .It Cm private Ar interface Mark an interface as a .Dq private interface. A private interface does not forward any traffic to any other port that is also a private interface. .It Cm -private Ar interface Clear the .Dq private attribute on a member interface. .It Cm span Ar interface Add the interface named by .Ar interface as a span port on the bridge. Span ports transmit a copy of every frame received by the bridge. This is most useful for snooping a bridged network passively on another host connected to one of the span ports of the bridge. .It Cm -span Ar interface Delete the interface named by .Ar interface from the list of span ports of the bridge. .It Cm stp Ar interface Enable Spanning Tree protocol on .Ar interface . The .Xr if_bridge 4 driver has support for the IEEE 802.1D Spanning Tree protocol (STP). Spanning Tree is used to detect and remove loops in a network topology. .It Cm -stp Ar interface Disable Spanning Tree protocol on .Ar interface . This is the default for all interfaces added to a bridge. .It Cm edge Ar interface Set .Ar interface as an edge port. An edge port connects directly to end stations cannot create bridging loops in the network, this allows it to transition straight to forwarding. .It Cm -edge Ar interface Disable edge status on .Ar interface . .It Cm autoedge Ar interface Allow .Ar interface to automatically detect edge status. This is the default for all interfaces added to a bridge. .It Cm -autoedge Ar interface Disable automatic edge status on .Ar interface . .It Cm ptp Ar interface Set the .Ar interface as a point to point link. This is required for straight transitions to forwarding and should be enabled on a direct link to another RSTP capable switch. .It Cm -ptp Ar interface Disable point to point link status on .Ar interface . This should be disabled for a half duplex link and for an interface connected to a shared network segment, like a hub or a wireless network. .It Cm autoptp Ar interface Automatically detect the point to point status on .Ar interface by checking the full duplex link status. This is the default for interfaces added to the bridge. .It Cm -autoptp Ar interface Disable automatic point to point link detection on .Ar interface . .It Cm maxage Ar seconds Set the time that a Spanning Tree protocol configuration is valid. The default is 20 seconds. The minimum is 6 seconds and the maximum is 40 seconds. .It Cm fwddelay Ar seconds Set the time that must pass before an interface begins forwarding packets when Spanning Tree is enabled. The default is 15 seconds. The minimum is 4 seconds and the maximum is 30 seconds. .It Cm hellotime Ar seconds Set the time between broadcasting of Spanning Tree protocol configuration messages. The hello time may only be changed when operating in legacy stp mode. The default is 2 seconds. The minimum is 1 second and the maximum is 2 seconds. .It Cm priority Ar value Set the bridge priority for Spanning Tree. The default is 32768. The minimum is 0 and the maximum is 61440. .It Cm proto Ar value Set the Spanning Tree protocol. The default is rstp. The available options are stp and rstp. .It Cm holdcnt Ar value Set the transmit hold count for Spanning Tree. This is the number of packets transmitted before being rate limited. The default is 6. The minimum is 1 and the maximum is 10. .It Cm ifpriority Ar interface Ar value Set the Spanning Tree priority of .Ar interface to .Ar value . The default is 128. The minimum is 0 and the maximum is 240. .It Cm ifpathcost Ar interface Ar value Set the Spanning Tree path cost of .Ar interface to .Ar value . The default is calculated from the link speed. To change a previously selected path cost back to automatic, set the cost to 0. The minimum is 1 and the maximum is 200000000. .It Cm ifmaxaddr Ar interface Ar size Set the maximum number of hosts allowed from an interface, packets with unknown source addresses are dropped until an existing host cache entry expires or is removed. Set to 0 to disable. .El .Pp The following parameters are specific to lagg interfaces: .Bl -tag -width indent .It Cm laggport Ar interface Add the interface named by .Ar interface as a port of the aggregation interface. .It Cm -laggport Ar interface Remove the interface named by .Ar interface from the aggregation interface. .It Cm laggproto Ar proto Set the aggregation protocol. The default is .Li failover . The available options are .Li failover , .Li lacp , .Li loadbalance , .Li roundrobin , .Li broadcast and .Li none . .It Cm lagghash Ar option Ns Oo , Ns Ar option Oc Set the packet layers to hash for aggregation protocols which load balance. The default is .Dq l2,l3,l4 . The options can be combined using commas. .Pp .Bl -tag -width ".Cm l2" -compact .It Cm l2 src/dst mac address and optional vlan number. .It Cm l3 src/dst address for IPv4 or IPv6. .It Cm l4 src/dst port for TCP/UDP/SCTP. .El .It Cm use_flowid Enable local hash computation for RSS hash on the interface. The .Li loadbalance and .Li lacp modes will use the RSS hash from the network card if available to avoid computing one, this may give poor traffic distribution if the hash is invalid or uses less of the protocol header information. .Cm use_flowid disables use of RSS hash from the network card. The default value can be set via the .Va net.link.lagg.default_use_flowid .Xr sysctl 8 variable. .Li 0 means .Dq disabled and .Li 1 means .Dq enabled . .It Cm -use_flowid Disable local hash computation for RSS hash on the interface. .It Cm flowid_shift Ar number Set a shift parameter for RSS local hash computation. Hash is calculated by using flowid bits in a packet header mbuf which are shifted by the number of this parameter. .El .Pp The following parameters are specific to IP tunnel interfaces, .Xr gif 4 : .Bl -tag -width indent .It Cm tunnel Ar src_addr dest_addr Configure the physical source and destination address for IP tunnel interfaces. The arguments .Ar src_addr and .Ar dest_addr are interpreted as the outer source/destination for the encapsulating IPv4/IPv6 header. .It Fl tunnel Unconfigure the physical source and destination address for IP tunnel interfaces previously configured with .Cm tunnel . .It Cm deletetunnel Another name for the .Fl tunnel parameter. .It Cm accept_rev_ethip_ver Set a flag to accept both correct EtherIP packets and ones with reversed version field. Enabled by default. This is for backward compatibility with .Fx 6.1 , 6.2, 6.3, 7.0, and 7.1. .It Cm -accept_rev_ethip_ver Clear a flag .Cm accept_rev_ethip_ver . .It Cm send_rev_ethip_ver Set a flag to send EtherIP packets with reversed version field intentionally. Disabled by default. This is for backward compatibility with .Fx 6.1 , 6.2, 6.3, 7.0, and 7.1. .It Cm -send_rev_ethip_ver Clear a flag .Cm send_rev_ethip_ver . .El .Pp The following parameters are specific to GRE tunnel interfaces, .Xr gre 4 : .Bl -tag -width indent .It Cm grekey Ar key Configure the GRE key to be used for outgoing packets. Note that .Xr gre 4 will always accept GRE packets with invalid or absent keys. This command will result in a four byte MTU reduction on the interface. .El .Pp The following parameters are specific to .Xr pfsync 4 interfaces: .Bl -tag -width indent .It Cm syncdev Ar iface Use the specified interface to send and receive pfsync state synchronisation messages. .It Fl syncdev Stop sending pfsync state synchronisation messages over the network. .It Cm syncpeer Ar peer_address Make the pfsync link point-to-point rather than using multicast to broadcast the state synchronisation messages. The peer_address is the IP address of the other host taking part in the pfsync cluster. .It Fl syncpeer Broadcast the packets using multicast. .It Cm maxupd Ar n Set the maximum number of updates for a single state which can be collapsed into one. This is an 8-bit number; the default value is 128. .It Cm defer Defer transmission of the first packet in a state until a peer has acknowledged that the associated state has been inserted. .It Fl defer Do not defer the first packet in a state. This is the default. .El .Pp The following parameters are specific to .Xr vlan 4 interfaces: .Bl -tag -width indent .It Cm vlan Ar vlan_tag Set the VLAN tag value to .Ar vlan_tag . This value is a 12-bit VLAN Identifier (VID) which is used to create an 802.1Q VLAN header for packets sent from the .Xr vlan 4 interface. Note that .Cm vlan and .Cm vlandev must both be set at the same time. .It Cm vlandev Ar iface Associate the physical interface .Ar iface with a .Xr vlan 4 interface. Packets transmitted through the .Xr vlan 4 interface will be diverted to the specified physical interface .Ar iface with 802.1Q VLAN encapsulation. Packets with 802.1Q encapsulation received by the parent interface with the correct VLAN Identifier will be diverted to the associated .Xr vlan 4 pseudo-interface. The .Xr vlan 4 interface is assigned a copy of the parent interface's flags and the parent's Ethernet address. The .Cm vlandev and .Cm vlan must both be set at the same time. If the .Xr vlan 4 interface already has a physical interface associated with it, this command will fail. To change the association to another physical interface, the existing association must be cleared first. .Pp Note: if the hardware tagging capability is set on the parent interface, the .Xr vlan 4 pseudo interface's behavior changes: the .Xr vlan 4 interface recognizes that the parent interface supports insertion and extraction of VLAN tags on its own (usually in firmware) and that it should pass packets to and from the parent unaltered. .It Fl vlandev Op Ar iface If the driver is a .Xr vlan 4 pseudo device, disassociate the parent interface from it. This breaks the link between the .Xr vlan 4 interface and its parent, clears its VLAN Identifier, flags and its link address and shuts the interface down. The .Ar iface argument is useless and hence deprecated. .El .Pp The following parameters are used to configure .Xr vxlan 4 interfaces. .Bl -tag -width indent .It Cm vxlanid Ar identifier This value is a 24-bit VXLAN Network Identifier (VNI) that identifies the virtual network segment membership of the interface. .It Cm vxlanlocal Ar address The source address used in the encapsulating IPv4/IPv6 header. The address should already be assigned to an existing interface. When the interface is configured in unicast mode, the listening socket is bound to this address. .It Cm vxlanremote Ar address The interface can be configured in a unicast, or point-to-point, mode to create a tunnel between two hosts. This is the IP address of the remote end of the tunnel. .It Cm vxlangroup Ar address The interface can be configured in a multicast mode to create a virtual network of hosts. This is the IP multicast group address the interface will join. .It Cm vxlanlocalport Ar port The port number the interface will listen on. The default port number is 4789. .It Cm vxlanremoteport Ar port The destination port number used in the encapsulating IPv4/IPv6 header. The remote host should be listening on this port. The default port number is 4789. Note some other implementations, such as Linux, do not default to the IANA assigned port, but instead listen on port 8472. .It Cm vxlanportrange Ar low high The range of source ports used in the encapsulating IPv4/IPv6 header. The port selected within the range is based on a hash of the inner frame. A range is useful to provide entropy within the outer IP header for more effective load balancing. The default range is between the .Xr sysctl 8 variables .Va net.inet.ip.portrange.first and .Va net.inet.ip.portrange.last .It Cm vxlantimeout Ar timeout The maximum time, in seconds, before an entry in the forwarding table is pruned. The default is 1200 seconds (20 minutes). .It Cm vxlanmaxaddr Ar max The maximum number of entries in the forwarding table. The default is 2000. .It Cm vxlandev Ar dev When the interface is configured in multicast mode, the .Cm dev interface is used to transmit IP multicast packets. .It Cm vxlanttl Ar ttl The TTL used in the encapsulating IPv4/IPv6 header. The default is 64. .It Cm vxlanlearn The source IP address and inner source Ethernet MAC address of received packets are used to dynamically populate the forwarding table. When in multicast mode, an entry in the forwarding table allows the interface to send the frame directly to the remote host instead of broadcasting the frame to the multicast group. This is the default. .It Fl vxlanlearn The forwarding table is not populated by recevied packets. .It Cm vxlanflush Delete all dynamically-learned addresses from the forwarding table. .It Cm vxlanflushall Delete all addresses, including static addresses, from the forwarding table. .El .Pp The following parameters are used to configure .Xr carp 4 protocol on an interface: .Bl -tag -width indent .It Cm vhid Ar n Set the virtual host ID. This is a required setting to initiate .Xr carp 4 . If the virtual host ID does not exist yet, it is created and attached to the interface, otherwise configuration of an existing vhid is adjusted. If the .Cm vhid keyword is supplied along with an .Dq inet6 or .Dq inet address, then this address is configured to be run under control of the specified vhid. Whenever a last address that refers to a particular vhid is removed from an interface, the vhid is automatically removed from interface and destroyed. Any other configuration parameters for the .Xr carp 4 protocol should be supplied along with the .Cm vhid keyword. Acceptable values for vhid are 1 to 255. .It Cm advbase Ar seconds Specifies the base of the advertisement interval in seconds. The acceptable values are 1 to 255. The default value is 1. .It Cm advskew Ar interval Specifies the skew to add to the base advertisement interval to make one host advertise slower than another host. It is specified in 1/256 of seconds. The acceptable values are 1 to 254. The default value is 0. .It Cm pass Ar phrase Set the authentication key to .Ar phrase . .It Cm state Ar MASTER|BACKUP Forcibly change state of a given vhid. .El .Pp The .Nm utility displays the current configuration for a network interface when no optional parameters are supplied. If a protocol family is specified, .Nm will report only the details specific to that protocol family. .Pp If the .Fl m flag is passed before an interface name, .Nm will display the capability list and all of the supported media for the specified interface. If .Fl L flag is supplied, address lifetime is displayed for IPv6 addresses, as time offset string. .Pp Optionally, the .Fl a flag may be used instead of an interface name. This flag instructs .Nm to display information about all interfaces in the system. The .Fl d flag limits this to interfaces that are down, and .Fl u limits this to interfaces that are up. When no arguments are given, .Fl a is implied. .Pp The .Fl l flag may be used to list all available interfaces on the system, with no other additional information. If an .Ar address_family is specified, only interfaces of that type will be listed. .Fl l Dq ether will list only Ethernet adapters, excluding the loopback interface. Use of this flag is mutually exclusive with all other flags and commands, except for .Fl d (only list interfaces that are down) and .Fl u (only list interfaces that are up). .Pp The .Fl v flag may be used to get more verbose status for an interface. .Pp The .Fl C flag may be used to list all of the interface cloners available on the system, with no additional information. Use of this flag is mutually exclusive with all other flags and commands. .Pp The .Fl k flag causes keying information for the interface, if available, to be printed. For example, the values of 802.11 WEP keys and .Xr carp 4 passphrases will be printed, if accessible to the current user. This information is not printed by default, as it may be considered sensitive. .Pp If the network interface driver is not present in the kernel then .Nm will attempt to load it. The .Fl n flag disables this behavior. .Pp Only the super-user may modify the configuration of a network interface. .Sh EXAMPLES Assign the IPv4 address .Li 192.0.2.10 , with a network mask of .Li 255.255.255.0 , to the interface .Li fxp0 : .Dl # ifconfig fxp0 inet 192.0.2.10 netmask 255.255.255.0 .Pp Add the IPv4 address .Li 192.0.2.45 , with the CIDR network prefix .Li /28 , to the interface .Li ed0 , using .Cm add as a synonym for the canonical form of the option .Cm alias : .Dl # ifconfig ed0 inet 192.0.2.45/28 add .Pp Remove the IPv4 address .Li 192.0.2.45 from the interface .Li ed0 : .Dl # ifconfig ed0 inet 192.0.2.45 -alias .Pp Enable IPv6 functionality of the interface: .Dl # ifconfig em0 inet6 -ifdisabled .Pp Add the IPv6 address .Li 2001:DB8:DBDB::123/48 to the interface .Li em0 : .Dl # ifconfig em0 inet6 2001:db8:bdbd::123 prefixlen 48 alias Note that lower case hexadecimal IPv6 addresses are acceptable. .Pp Remove the IPv6 address added in the above example, using the .Li / character as shorthand for the network prefix, and using .Cm delete as a synonym for the canonical form of the option .Fl alias : .Dl # ifconfig em0 inet6 2001:db8:bdbd::123/48 delete .Pp Configure a single CARP redundant address on igb0, and then switch it to be master: .Dl # ifconfig igb0 vhid 1 10.0.0.1/24 pass foobar up .Dl # ifconfig igb0 vhid 1 state master .Pp Configure the interface .Li xl0 , to use 100baseTX, full duplex Ethernet media options: .Dl # ifconfig xl0 media 100baseTX mediaopt full-duplex .Pp Label the em0 interface as an uplink: .Dl # ifconfig em0 description \&"Uplink to Gigabit Switch 2\&" .Pp Create the software network interface .Li gif1 : .Dl # ifconfig gif1 create .Pp Destroy the software network interface .Li gif1 : .Dl # ifconfig gif1 destroy .Pp Display available wireless networks using .Li wlan0 : .Dl # ifconfig wlan0 list scan .Sh DIAGNOSTICS Messages indicating the specified interface does not exist, the requested address is unknown, or the user is not privileged and tried to alter an interface's configuration. .Sh SEE ALSO .Xr netstat 1 , .Xr carp 4 , .Xr gif 4 , .Xr netintro 4 , .Xr pfsync 4 , .Xr polling 4 , .Xr vlan 4 , .Xr vxlan 4 , .Xr devd.conf 5 , .\" .Xr eon 5 , .Xr devd 8 , +.Xr jail 8 , .Xr rc 8 , .Xr routed 8 , -.Xr jail 8 , .Xr sysctl 8 .Sh HISTORY The .Nm utility appeared in .Bx 4.2 . .Sh BUGS Basic IPv6 node operation requires a link-local address on each interface configured for IPv6. Normally, such an address is automatically configured by the kernel on each interface added to the system or enabled; this behavior may be disabled by setting per-interface flag .Cm -auto_linklocal . The default value of this flag is 1 and can be disabled by using the sysctl MIB variable .Va net.inet6.ip6.auto_linklocal . .Pp Do not configure IPv6 addresses with no link-local address by using .Nm . It can result in unexpected behaviors of the kernel. Index: head/sbin/iscontrol/iscontrol.8 =================================================================== --- head/sbin/iscontrol/iscontrol.8 (revision 276292) +++ head/sbin/iscontrol/iscontrol.8 (revision 276293) @@ -1,137 +1,137 @@ .\" Copyright (c) 2007-2010 Daniel Braniss .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 9, 2014 .Dt ISCONTROL 8 .Os .Sh NAME .Nm iscontrol .Nd login/negotiator/control for an iSCSI initiator session .Sh SYNOPSIS .Nm .Op Fl dv .Oo .Fl c Ar file .Op Fl n Ar nickname .Oc .Op Fl p Ar pidfile .Op Fl t Ar target .Op Ar variable Ns = Ns Ar value .Sh DESCRIPTION .Bf -symbolic This command, along with its kernel counterpart .Xr iscsi_initiator 4 , is obsolete. Users are advised to use .Xr iscsictl 8 instead. .Ef .Pp Internet SCSI (iSCSI) is a network protocol standard, that allows the use of the SCSI protocol over TCP/IP networks, the .Nm program is the userland side of an iSCSI session, see .Xr iscsi_initiator 4 . It has 2 modes of operation, if -d (discovery session) is specified, it will print out the .Em target names returned by the target and exit. In the second mode, it will, after a successful login/negotiation, run in daemon mode, monitoring the connection, and will try to reconnect in case of a network/target failure. It will terminate/logout the session when a SIGHUP signal is received. The flags are as follows: .Bl -tag -width variable=value .It Fl c Ar file a file containing configuration .Em key-options , see .Xr iscsi.conf 5 . .It Fl d do a .Em discovery session and exit. .It Fl n Ar nickname if .Sy -c file is specified, then search for the block named .Em nickname in that file, see .Xr iscsi.conf 5 . .It Fl p Ar pidfile will write the process ID of the session to the specified .Em pidfile .It Fl t Ar target the target's IP address or name. .It Fl v verbose mode. .It Ar variable Ns = Ns Ar value see .Xr iscsi.conf 5 for the complete list of variables/options and their possible values. .El .Sh EXAMPLES .Dl iscontrol -dt myiscsitarget .Pp will start a .Em discovery session with the target and print to stdout the list of available targetnames/targetadresses. Note: this listing does not necessarily mean availability, since depending on the target configuration, a discovery session might not need login/access permission, but a .Em full session certainly does. .sp .Dl iscontrol -c /etc/iscsi.conf -n myiscsi .Pp will read options from .Pa /etc/iscsi.conf , use the targetaddress found in the block nicknamed myiscsi, login and negotiate whatever options are specified, and start an iscsi-session. .Sh SEE ALSO .Xr da 4 , .Xr iscsi_initiator 4 , .Xr sa 4 , .Xr iscsi.conf 5 , -.Xr iscsictl 8 , -.Xr camcontrol 8 +.Xr camcontrol 8 , +.Xr iscsictl 8 .Sh STANDARDS RFC 3720 .\"Sh HISTORY .Sh BUGS .Nm should probably load the iscsi_initiator module if needed. .br Not all functions/specifications have been implemented yet, noticeably missing are the Task Management Functions. The error recovery, though not .Em fully compliant does a brave effort to recover from network disconnects. Index: head/sbin/mount/mount.8 =================================================================== --- head/sbin/mount/mount.8 (revision 276292) +++ head/sbin/mount/mount.8 (revision 276293) @@ -1,593 +1,593 @@ .\" Copyright (c) 1980, 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mount.8 8.8 (Berkeley) 6/16/94 .\" $FreeBSD$ .\" .Dd December 3, 2014 .Dt MOUNT 8 .Os .Sh NAME .Nm mount .Nd mount file systems .Sh SYNOPSIS .Nm .Op Fl adflpruvw .Op Fl F Ar fstab .Op Fl o Ar options .Op Fl t Cm ufs | Ar external_type .Nm .Op Fl dfpruvw .Ar special | node .Nm .Op Fl dfpruvw .Op Fl o Ar options .Op Fl t Cm ufs | Ar external_type .Ar special node .Sh DESCRIPTION The .Nm utility calls the .Xr nmount 2 system call to prepare and graft a .Ar special device or the remote node (rhost:path) on to the file system tree at the point .Ar node . If either .Ar special or .Ar node are not provided, the appropriate information is taken from the .Xr fstab 5 file. .Pp The system maintains a list of currently mounted file systems. If no arguments are given to .Nm , this list is printed. .Pp The options are as follows: .Bl -tag -width indent .It Fl a All the file systems described in .Xr fstab 5 are mounted. Exceptions are those marked as .Dq Li noauto , those marked as .Dq Li late (unless the .Fl l option was specified), those excluded by the .Fl t flag (see below), or if they are already mounted (except the root file system which is always remounted to preserve traditional single user mode behavior). .It Fl d Causes everything to be done except for the actual system call. This option is useful in conjunction with the .Fl v flag to determine what the .Nm command is trying to do. .It Fl F Ar fstab Specify the .Pa fstab file to use. .It Fl f Forces the revocation of write access when trying to downgrade a file system mount status from read-write to read-only. Also forces the R/W mount of an unclean file system (dangerous; use with caution). .It Fl L When used in conjunction with the .Fl a option, mount .Em only those file systems which are marked as .Dq Li late . .It Fl l When used in conjunction with the .Fl a option, also mount those file systems which are marked as .Dq Li late . .It Fl n For compatibility with some other implementations, this flag is currently a no-op. .It Fl o Options are specified with a .Fl o flag followed by a comma separated string of options. In case of conflicting options being specified, the rightmost option takes effect. The following options are available: .Bl -tag -width indent .It Cm acls Enable POSIX.1e Access Control Lists, or ACLs, which can be customized via the .Xr setfacl 1 and .Xr getfacl 1 commands. This flag is mutually exclusive with .Cm nfsv4acls flag. .It Cm async All .Tn I/O to the file system should be done asynchronously. This is a .Em dangerous flag to set, since it does not guarantee that the file system structure on the disk will remain consistent. For this reason, the .Cm async flag should be used sparingly, and only when some data recovery mechanism is present. .It Cm automounted This flag indicates that the file system was mounted by .Xr automountd 8 . Automounted file systems are automatically unmounted by .Xr autounmountd 8 . .It Cm current When used with the .Fl u flag, this is the same as specifying the options currently in effect for the mounted file system. .It Cm force The same as .Fl f ; forces the revocation of write access when trying to downgrade a file system mount status from read-write to read-only. Also forces the R/W mount of an unclean file system (dangerous; use with caution). .It Cm fstab When used with the .Fl u flag, this is the same as specifying all the options listed in the .Xr fstab 5 file for the file system. .It Cm late This file system should be skipped when .Nm is run with the .Fl a flag but without the .Fl l flag. .It Cm mountprog Ns = Ns Aq Ar program Force .Nm to use the specified program to mount the file system, instead of calling .Xr nmount 2 directly. For example: .Bd -literal mount -t foofs -o mountprog=/mydir/fooprog /dev/acd0 /mnt .Ed .It Cm multilabel Enable multi-label Mandatory Access Control, or MAC, on the specified file system. If the file system supports multilabel operation, individual labels will be maintained for each object in the file system, rather than using a single label for all objects. An alternative to the .Fl l flag in .Xr tunefs 8 . See .Xr mac 4 for more information, which cause the multilabel mount flag to be set automatically at mount-time. .It Cm nfsv4acls Enable NFSv4 ACLs, which can be customized via the .Xr setfacl 1 and .Xr getfacl 1 commands. This flag is mutually exclusive with .Cm acls flag. .It Cm noasync Metadata I/O should be done synchronously, while data I/O should be done asynchronously. This is the default. .It Cm noatime Do not update the file access time when reading from a file. This option is useful on file systems where there are large numbers of files and performance is more critical than updating the file access time (which is rarely ever important). This option is currently only supported on local file systems. .It Cm noauto This file system should be skipped when .Nm is run with the .Fl a flag. .It Cm noclusterr Disable read clustering. .It Cm noclusterw Disable write clustering. .It Cm noexec Do not allow execution of any binaries on the mounted file system. This option is useful for a server that has file systems containing binaries for architectures other than its own. Note: This option was not designed as a security feature and no guarantee is made that it will prevent malicious code execution; for example, it is still possible to execute scripts which reside on a .Cm noexec mounted partition. .It Cm nosuid Do not allow set-user-identifier or set-group-identifier bits to take effect. Note: this option is worthless if a public available suid or sgid wrapper like .Xr suidperl 1 is installed on your system. It is set automatically when the user does not have super-user privileges. .It Cm nosymfollow Do not follow symlinks on the mounted file system. .It Cm ro The same as .Fl r ; mount the file system read-only (even the super-user may not write it). .It Cm snapshot This option allows a snapshot of the specified file system to be taken. The .Fl u flag is required with this option. Note that snapshot files must be created in the file system that is being snapshotted. You may create up to 20 snapshots per file system. Active snapshots are recorded in the superblock, so they persist across unmount and remount operations and across system reboots. When you are done with a snapshot, it can be removed with the .Xr rm 1 command. Snapshots may be removed in any order, however you may not get back all the space contained in the snapshot as another snapshot may claim some of the blocks that it is releasing. Note that the schg flag is set on snapshots to ensure that not even the root user can write to them. The unlink command makes an exception for snapshot files in that it allows them to be removed even though they have the schg flag set, so it is not necessary to clear the schg flag before removing a snapshot file. .Pp Once you have taken a snapshot, there are three interesting things that you can do with it: .Pp .Bl -enum -compact .It Run .Xr fsck 8 on the snapshot file. Assuming that the file system was clean when it was mounted, you should always get a clean (and unchanging) result from running fsck on the snapshot. This is essentially what the background fsck process does. .Pp .It Run .Xr dump 8 on the snapshot. You will get a dump that is consistent with the file system as of the timestamp of the snapshot. .Pp .It Mount the snapshot as a frozen image of the file system. To mount the snapshot .Pa /var/snapshot/snap1 : .Bd -literal mdconfig -a -t vnode -f /var/snapshot/snap1 -u 4 mount -r /dev/md4 /mnt .Ed .Pp You can now cruise around your frozen .Pa /var file system at .Pa /mnt . Everything will be in the same state that it was at the time the snapshot was taken. The one exception is that any earlier snapshots will appear as zero length files. When you are done with the mounted snapshot: .Bd -literal umount /mnt mdconfig -d -u 4 .Ed .El .It Cm suiddir A directory on the mounted file system will respond to the SUID bit being set, by setting the owner of any new files to be the same as the owner of the directory. New directories will inherit the bit from their parents. Execute bits are removed from the file, and it will not be given to root. .Pp This feature is designed for use on fileservers serving PC users via ftp, SAMBA, or netatalk. It provides security holes for shell users and as such should not be used on shell machines, especially on home directories. This option requires the SUIDDIR option in the kernel to work. Only UFS file systems support this option. See .Xr chmod 2 for more information. .It Cm sync All .Tn I/O to the file system should be done synchronously. .It Cm update The same as .Fl u ; indicate that the status of an already mounted file system should be changed. .It Cm union Causes the namespace at the mount point to appear as the union of the mounted file system root and the existing directory. Lookups will be done in the mounted file system first. If those operations fail due to a non-existent file the underlying directory is then accessed. All creates are done in the mounted file system. .El .Pp Any additional options specific to a file system type that is not one of the internally known types (see the .Fl t option) may be passed as a comma separated list; these options are distinguished by a leading .Dq \&- (dash). For example, the .Nm command: .Bd -literal -offset indent mount -t cd9660 -o -e /dev/cd0 /cdrom .Ed .Pp causes .Nm to execute the equivalent of: .Bd -literal -offset indent /sbin/mount_cd9660 -e /dev/cd0 /cdrom .Ed .Pp Options that take a value are specified using the -option=value syntax: .Bd -literal -offset indent mount -t msdosfs -o -u=fred,-g=wheel /dev/da0s1 /mnt .Ed .Pp is equivalent to .Bd -literal -offset indent /sbin/mount_msdosfs -u fred -g wheel /dev/da0s1 /mnt .Ed .Pp Additional options specific to file system types which are not internally known (see the description of the .Fl t option below) may be described in the manual pages for the associated .Pa /sbin/mount_ Ns Sy XXX utilities. .It Fl p Print mount information in .Xr fstab 5 format. Implies also the .Fl v option. .It Fl r The file system is to be mounted read-only. Mount the file system read-only (even the super-user may not write it). The same as the .Cm ro argument to the .Fl o option. .It Fl t Cm ufs | Ar external_type The argument following the .Fl t is used to indicate the file system type. The type .Cm ufs is the default. The .Fl t option can be used to indicate that the actions should only be taken on file systems of the specified type. More than one type may be specified in a comma separated list. The list of file system types can be prefixed with .Dq Li no to specify the file system types for which action should .Em not be taken. For example, the .Nm command: .Bd -literal -offset indent mount -a -t nonfs,nullfs .Ed .Pp mounts all file systems except those of type .Tn NFS and .Tn NULLFS . .Pp The default behavior of .Nm is to pass the .Fl t option directly to the .Xr nmount 2 system call in the .Li fstype option. .Pp However, for the following file system types: .Cm cd9660 , .Cm mfs , .Cm msdosfs , .Cm nfs , .Cm nullfs , .Cm oldnfs , .Cm smbfs , .Cm udf , and .Cm unionfs . .Nm will not call .Xr nmount 2 directly and will instead attempt to execute a program in .Pa /sbin/mount_ Ns Sy XXX where .Sy XXX is replaced by the file system type name. For example, nfs file systems are mounted by the program .Pa /sbin/mount_nfs . .Pp Most file systems will be dynamically loaded by the kernel if not already present, and if the kernel module is available. .It Fl u The .Fl u flag indicates that the status of an already mounted file system should be changed. Any of the options discussed above (the .Fl o option) may be changed; also a file system can be changed from read-only to read-write or vice versa. An attempt to change from read-write to read-only will fail if any files on the file system are currently open for writing unless the .Fl f flag is also specified. The set of options is determined by applying the options specified in the argument to .Fl o and finally applying the .Fl r or .Fl w option. .It Fl v Verbose mode. If the .Fl v is used alone, show all file systems, including those that were mounted with the .Dv MNT_IGNORE flag and show additional information about each file system (including fsid when run by root). .It Fl w The file system object is to be read and write. .El .Sh ENVIRONMENT .Bl -tag -width ".Ev PATH_FSTAB" .It Ev PATH_FSTAB If the environment variable .Ev PATH_FSTAB is set, all operations are performed against the specified file. .Ev PATH_FSTAB will not be honored if the process environment or memory address space is considered .Dq tainted . (See .Xr issetugid 2 for more information.) .El .Sh FILES .Bl -tag -width /etc/fstab -compact .It Pa /etc/fstab file system table .El .Sh DIAGNOSTICS Various, most of them are self-explanatory. .Pp .Dl XXXXX file system is not available .Pp The kernel does not support the respective file system type. Note that support for a particular file system might be provided either on a static (kernel compile-time), or dynamic basis (loaded as a kernel module by .Xr kldload 8 ) . .Sh SEE ALSO .Xr getfacl 1 , .Xr setfacl 1 , .Xr nmount 2 , .Xr acl 3 , .Xr mac 4 , .Xr devfs 5 , .Xr ext2fs 5 , .Xr fstab 5 , .Xr procfs 5 , +.Xr tmpfs 5 , .Xr automount 8 , .Xr fstyp 8 , .Xr kldload 8 , .Xr mount_cd9660 8 , .Xr mount_msdosfs 8 , .Xr mount_nfs 8 , .Xr mount_nullfs 8 , .Xr mount_smbfs 8 , .Xr mount_udf 8 , .Xr mount_unionfs 8 , -.Xr tmpfs 5 , .Xr umount 8 , .Xr zfs 8 , .Xr zpool 8 .Sh HISTORY A .Nm utility appeared in .At v1 . .Sh CAVEATS After a successful .Nm , the permissions on the original mount point determine if .Pa ..\& is accessible from the mounted file system. The minimum permissions for the mount point for traversal across the mount point in both directions to be possible for all users is 0111 (execute for all). .Pp Use of the .Nm is preferred over the use of the file system specific .Pa mount_ Ns Sy XXX commands. In particular, .Xr mountd 8 gets a .Dv SIGHUP signal (that causes an update of the export list) only when the file system is mounted via .Nm . .Sh BUGS It is possible for a corrupted file system to cause a crash. Index: head/sbin/mount_fusefs/mount_fusefs.8 =================================================================== --- head/sbin/mount_fusefs/mount_fusefs.8 (revision 276292) +++ head/sbin/mount_fusefs/mount_fusefs.8 (revision 276293) @@ -1,362 +1,362 @@ .\" Copyright (c) 1980, 1989, 1991, 1993 .\" The Regents of the University of California. .\" Copyright (c) 2005, 2006 Csaba Henk .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 11, 2012 .Dt MOUNT_FUSEFS 8 .Os .Sh NAME .Nm mount_fusefs .Nd mount a Fuse file system daemon .Sh SYNOPSIS .Nm .Op Fl A .Op Fl S .Op Fl v .Op Fl D Ar fuse_daemon .Op Fl O Ar daemon_opts .Op Fl s Ar special .Op Fl m Ar node .Op Fl h .Op Fl V .Op Fl o Ar option ... .Ar special node .Op Ar fuse_daemon ... .Sh DESCRIPTION Basic usage is to start a fuse daemon on the given .Ar special file. In practice, the daemon is assigned a .Ar special file automatically, which can then be indentified via .Xr fstat 1 . That special file can then be mounted by .Nm . .Pp However, the procedure of spawning a daemon will usually be automated so that it is performed by .Nm . If the command invoking a given .Ar fuse_daemon is appended to the list of arguments, .Nm will call the .Ar fuse_daemon via that command. In that way the .Ar fuse_daemon will be instructed to attach itself to .Ar special . From that on mounting goes as in the simple case. (See .Sx DAEMON MOUNTS . ) .Pp The .Ar special argument will normally be treated as the path of the special file to mount. .Pp However, if .Pa auto is passed as .Ar special , then .Nm will look for a suitable free fuse device by itself. .Pp Finally, if .Ar special is an integer it will be interpreted as the number of the file descriptor of an already open fuse device (used when the Fuse library invokes .Nm . (See .Sx DAEMON MOUNTS ) . .Pp The options are as follows: .Bl -tag -width indent .It Fl A , Ic --reject-allow_other Prohibit the .Cm allow_other mount flag. Intended for use in scripts and the .Xr sudoers 5 file. .It Fl S , Ic --safe Run in safe mode (i.e. reject invoking a filesystem daemon) .It Fl v Be verbose .It Fl D, Ic --daemon Ar daemon Call the specified .Ar daemon .It Fl O, Ic --daemon_opts Ar opts Add .Ar opts to the daemon's command line .It Fl s, Ic --special Ar special Use .Ar special as special .It Fl m, Ic --mountpath Ar node Mount on .Ar node .It Fl h, Ic --help Show help .It Fl V, Ic --version Show version information .It Fl o Mount options are specified via .Fl o . The following options are available (and also their negated versions, by prefixing them with .Dq no ) : .Bl -tag -width indent .It Cm default_permissions Enable traditional (file mode based) permission checking in kernel .It Cm allow_other Do not apply .Sx STRICT ACCESS POLICY . Only root can use this option .It Cm max_read Ns = Ns Ar n Limit size of read requests to .Ar n .It Cm private Refuse shared mounting of the daemon. This is the default behaviour, to allow sharing, expicitly use .Fl o Cm noprivate .It Cm neglect_shares Do not refuse unmounting if there are secondary mounts .It Cm push_symlinks_in Prefix absolute symlinks with the mountpoint .El .El .Pp Besides the above mount options, there is a set of pseudo-mount options which are supported by the Fuse library. One can list these by passing .Fl h to a Fuse daemon. Most of these options have effect only on the behaviour of the daemon (that is, their scope is limited to userspace). However, there are some which do require in-kernel support. Currently the options supported by the kernel are: .Bl -tag -width indent .It Cm direct_io Bypass the buffer cache system .It Cm kernel_cache By default cached buffers of a given file are flushed at each .Xr open 2 . This option disables this behaviour .El .Sh DAEMON MOUNTS Usually users do not need to use .Nm directly, as the Fuse library enables Fuse daemons to invoke .Nm . That is, .Pp .Dl fuse_daemon device mountpoint .Pp has the same effect as .Pp .Dl mount_fusefs auto mountpoint fuse_daemon .Pp This is the recommended usage when you want basic usage (eg, run the daemon at a low privilege level but mount it as root). .Sh STRICT ACCESS POLICY The strict access policy for Fuse filesystems lets one to use the filesystem only if the filesystem daemon has the same credentials (uid, real uid, gid, real gid) as the user. .Pp This is applied for Fuse mounts by default and only root can mount without the strict access policy (ie. the .Cm allow_other mount option). .Pp This is to shield users from the daemon .Dq spying on their I/O activities. .Pp Users might opt to willingly relax strict access policy (as far they are concerned) by doing their own secondary mount (See .Sx SHARED MOUNTS ) . .Sh SHARED MOUNTS A Fuse daemon can be shared (ie. mounted multiple times). When doing the first (primary) mount, the spawner and the mounter of the daemon must have the same uid, or the mounter should be the superuser. .Pp After the primary mount is in place, secondary mounts can be done by anyone unless this feature is disabled by .Cm private . The behaviour of a secondary mount is analogous to that of symbolic links: they redirect all filesystem operations to the primary mount. .Pp Doing a secondary mount is like signing an agreement: by this action, the mounter agrees that the Fuse daemon can trace her I/O activities. From then on she is not banned from using the filesystem (either via her own mount or via the primary mount), regardless whether .Cm allow_other is used or not. .Pp The device name of a secondary mount is the device name of the corresponding primary mount, followed by a '#' character and the index of the secondary mount; e.g. .Pa /dev/fuse0#3 . .Sh SECURITY System administrators might want to use a custom mount policy (ie., one going beyond the .Va vfs.usermount sysctl). The primary tool for such purposes is .Xr sudo 8 . However, given that .Nm is capable of invoking an arbitrary program, one must be careful when doing this. .Nm is designed in a way such that it makes that easy. For this purpose, there are options which disable certain risky features (ie. .Fl S and .Fl A ) , and command line parsing is done in a flexible way: mixing options and non-options is allowed, but processing them stops at the third non-option argument (after the first two has been utilized as device and mountpoint). The rest of the command line specifies the daemon and its arguments. (Alternatively, the daemon, the special and the mount path can be specified using the respective options.) Note that .Nm ignores the environment variable .Ev POSIXLY_CORRECT and always behaves as described. .Pp In general, to be as scripting / .Xr sudoers 5 friendly as possible, no information has a fixed position in the command line, but once a given piece of information is provided, subsequent arguments/options cannot override it (with the exception of some non-critical ones). .Sh ENVIRONMENT .Bl -tag -width ".Ev MOUNT_FUSEFS_SAFE" .It Ev MOUNT_FUSEFS_SAFE This has the same effect as the .Fl S option. .It Ev MOUNT_FUSEFS_VERBOSE This has the same effect as the .Fl v option. .It Ev MOUNT_FUSEFS_IGNORE_UNKNOWN If set, .Nm will ignore uknown mount options. .It Ev MOUNT_FUSEFS_CALL_BY_LIB Adjust behaviour to the needs of the FUSE library. Currently it effects help output. .El .Pp Although the following variables do not have any effect on .Nm itself, they affect the behaviour of fuse daemons: .Bl -tag -width ".Ev FUSE_DEV_NAME" .It Ev FUSE_DEV_NAME Device to attach. If not set, the multiplexer path .Ar /dev/fuse is used. .It Ev FUSE_DEV_FD File desciptor of an opened Fuse device to use. Overrides .Ev FUSE_DEV_NAME . .It Ev FUSE_NO_MOUNT If set, the library will not attempt to mount the filesystem, even if a mountpoint argument is supplied. .El .Sh FILES .Bl -tag -width /dev/fuse .It Pa /dev/fuse Fuse device with which the kernel and Fuse daemons can communicate. .It Pa /dev/fuse The multiplexer path. An .Xr open 2 performed on it automatically is passed to a free Fuse device by the kernel (which might be created just for this puprose). .El .Sh EXAMPLES Mount the example filesystem in the Fuse distribution (from its directory): either .Pp .Dl ./fusexmp /mnt/fuse .Pp or .Pp .Dl mount_fusefs auto /mnt/fuse ./fusexmp .Pp Doing the same in two steps, using .Pa /dev/fuse0 : .Pp .Dl FUSE_DEV_NAME=/dev/fuse ./fusexmp && .Dl mount_fusefs /dev/fuse /mnt/fuse .Pp A script wrapper for fusexmp which ensures that .Nm does not call any external utility and also provides a hacky (non race-free) automatic device selection: .Pp .Dl #!/bin/sh -e .Pp .Dl FUSE_DEV_NAME=/dev/fuse fusexmp .Dl mount_fusefs -S /dev/fuse /mnt/fuse \(lq$@\(rq .Sh SEE ALSO .Xr fstat 1 , .Xr mount 8 , -.Xr umount 8 , -.Xr sudo 8 +.Xr sudo 8 , +.Xr umount 8 .Sh HISTORY .Nm appears as the part of the FreeBSD implementation of the Fuse userspace filesystem framework (see http://fuse.sourceforge.net). This user interface is FreeBSD specific. .Sh CAVEATS Secondary mounts should be unmounted via their device name. If an attempt is made to be unmount them via their filesystem root path, the unmount request will be forwarded to the primary mount path. In general, unmounting by device name is less error-prone than by mount path (although the latter will also work under normal circumstances). .Pp If the daemon is specified via the .Fl D and .Fl O options, it will be invoked via .Xr system 3 , and the daemon's command line will also have an .Dq & control operator appended, so that we do not have to wait for its termination. You should use a simple command line when invoking the daemon via these options. .Sh BUGS .Ar special is treated as a multiplexer if and only if it is literally the same as .Pa auto or .Pa /dev/fuse . Other paths which are equivalent with .Pa /dev/fuse (eg., .Pa /../dev/fuse ) are not. Index: head/sbin/newfs/newfs.8 =================================================================== --- head/sbin/newfs/newfs.8 (revision 276292) +++ head/sbin/newfs/newfs.8 (revision 276293) @@ -1,333 +1,333 @@ .\" Copyright (c) 1983, 1987, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)newfs.8 8.6 (Berkeley) 5/3/95 .\" $FreeBSD$ .\" .Dd October 1, 2013 .Dt NEWFS 8 .Os .Sh NAME .Nm newfs .Nd construct a new UFS1/UFS2 file system .Sh SYNOPSIS .Nm .Op Fl EJNUjlnt .Op Fl L Ar volname .Op Fl O Ar filesystem-type .Op Fl S Ar sector-size .Op Fl T Ar disktype .Op Fl a Ar maxcontig .Op Fl b Ar block-size .Op Fl c Ar blocks-per-cylinder-group .Op Fl d Ar max-extent-size .Op Fl e Ar maxbpg .Op Fl f Ar frag-size .Op Fl g Ar avgfilesize .Op Fl h Ar avgfpdir .Op Fl i Ar bytes .Op Fl k Ar held-for-metadata-blocks .Op Fl m Ar free-space .Op Fl o Ar optimization .Op Fl p Ar partition .Op Fl r Ar reserved .Op Fl s Ar size .Ar special .Sh DESCRIPTION The .Nm utility is used to initialize and clear file systems before first use. The .Nm utility builds a file system on the specified special file. (We often refer to the .Dq special file as the .Dq disk , although the special file need not be a physical disk. In fact, it need not even be special.) Typically the defaults are reasonable, however .Nm has numerous options to allow the defaults to be selectively overridden. .Pp The following options define the general layout policies: .Bl -tag -width indent .It Fl E Erase the content of the disk before making the filesystem. The reserved area in front of the superblock (for bootcode) will not be erased. .Pp This option is only relevant for flash based storage devices that use wear-leveling algorithms. .Pp Erasing may take a long time as it writes to every sector on the disk. .It Fl J Enable journaling on the new file system via gjournal. See .Xr gjournal 8 for details. .It Fl L Ar volname Add a volume label to the new file system. .It Fl N Cause the file system parameters to be printed out without really creating the file system. .It Fl O Ar filesystem-type Use 1 to specify that a UFS1 format file system be built; use 2 to specify that a UFS2 format file system be built. The default format is UFS2. .It Fl T Ar disktype For backward compatibility. .It Fl U Enable soft updates on the new file system. .It Fl a Ar maxcontig Specify the maximum number of contiguous blocks that will be laid out before forcing a rotational delay. The default value is 16. See .Xr tunefs 8 for more details on how to set this option. .It Fl b Ar block-size The block size of the file system, in bytes. It must be a power of 2. The default size is 32768 bytes, and the smallest allowable size is 4096 bytes. The optimal block:fragment ratio is 8:1. Other ratios are possible, but are not recommended, and may produce poor results. .It Fl c Ar blocks-per-cylinder-group The number of blocks per cylinder group in a file system. The default is to compute the maximum allowed by the other parameters. This value is dependent on a number of other parameters, in particular the block size and the number of bytes per inode. .It Fl d Ar max-extent-size The file system may choose to store large files using extents. This parameter specifies the largest extent size that may be used. The default value is the file system blocksize. It is presently limited to a maximum value of 16 times the file system blocksize and a minimum value of the file system blocksize. .It Fl e Ar maxbpg Indicate the maximum number of blocks any single file can allocate out of a cylinder group before it is forced to begin allocating blocks from another cylinder group. The default is about one quarter of the total blocks in a cylinder group. See .Xr tunefs 8 for more details on how to set this option. .It Fl f Ar frag-size The fragment size of the file system in bytes. It must be a power of two ranging in value between .Ar blocksize Ns /8 and .Ar blocksize . The default is 4096 bytes. .It Fl g Ar avgfilesize The expected average file size for the file system. .It Fl h Ar avgfpdir The expected average number of files per directory on the file system. .It Fl i Ar bytes Specify the density of inodes in the file system. The default is to create an inode for every .Pq 4 * Ar frag-size bytes of data space. If fewer inodes are desired, a larger number should be used; to create more inodes a smaller number should be given. One inode is required for each distinct file, so this value effectively specifies the average file size on the file system. .It Fl j Enable soft updates journaling on the new file system. This flag is implemented by running the .Xr tunefs 8 utility found in the user's .Dv $PATH . .It Fl k Ar held-for-metadata-blocks Set the amount of space to be held for metadata blocks in each cylinder group. When set, the file system preference routines will try to save the specified amount of space immediately following the inode blocks in each cylinder group for use by metadata blocks. Clustering the metadata blocks speeds up random file access and decreases the running time of .Xr fsck 8 . By default .Xr newfs 8 sets it to half of the space reserved to minfree. .It Fl l Enable multilabel MAC on the new file system. .It Fl m Ar free-space The percentage of space reserved from normal users; the minimum free space threshold. The default value used is defined by .Dv MINFREE from .In ufs/ffs/fs.h , currently 8%. See .Xr tunefs 8 for more details on how to set this option. .It Fl n Do not create a .Pa .snap directory on the new file system. The resulting file system will not support snapshot generation, so .Xr dump 8 in live mode and background .Xr fsck 8 will not function properly. The traditional .Xr fsck 8 and offline .Xr dump 8 will work on the file system. This option is intended primarily for memory or vnode-backed file systems that do not require .Xr dump 8 or .Xr fsck 8 support. .It Fl o Ar optimization .Cm ( space or .Cm time ) . The file system can either be instructed to try to minimize the time spent allocating blocks, or to try to minimize the space fragmentation on the disk. If the value of minfree (see above) is less than 8%, the default is to optimize for .Cm space ; if the value of minfree is greater than or equal to 8%, the default is to optimize for .Cm time . See .Xr tunefs 8 for more details on how to set this option. .It Fl p Ar partition The partition name (a..h) you want to use in case the underlying image is a file, so you do not have access to individual partitions through the filesystem. Can also be used with a device, e.g. .Nm .Fl p Ar f .Ar /dev/da1s3 is equivalent to .Nm .Ar /dev/da1s3f . .It Fl r Ar reserved The size, in sectors, of reserved space at the end of the partition specified in .Ar special . This space will not be occupied by the file system; it can be used by other consumers such as .Xr geom 4 . Defaults to 0. .It Fl s Ar size The size of the file system in sectors. This value defaults to the size of the raw partition specified in .Ar special less the .Ar reserved space at its end (see .Fl r ) . A .Ar size of 0 can also be used to choose the default value. A valid .Ar size value cannot be larger than the default one, which means that the file system cannot extend into the reserved space. .It Fl t Turn on the TRIM enable flag. If enabled, and if the underlying device supports the BIO_DELETE command, the file system will send a delete request to the underlying device for each freed block. The trim enable flag is typically set when the underlying device uses flash-memory as the device can use the delete command to pre-zero or at least avoid copying blocks that have been deleted. .El .Pp The following options override the standard sizes for the disk geometry. Their default values are taken from the disk label. Changing these defaults is useful only when using .Nm to build a file system whose raw image will eventually be used on a different type of disk than the one on which it is initially created (for example on a write-once disk). Note that changing any of these values from their defaults will make it impossible for .Xr fsck 8 to find the alternate superblocks if the standard superblock is lost. .Bl -tag -width indent .It Fl S Ar sector-size The size of a sector in bytes (almost never anything but 512). .El .Sh EXAMPLES .Dl newfs /dev/ada3s1a .Pp Creates a new ufs file system on .Pa ada3s1a . The .Nm utility will use a block size of 32768 bytes, a fragment size of 4096 bytes and the largest possible number of blocks per cylinders group. These values tend to produce better performance for most applications than the historical defaults (8192 byte block size and 1024 byte fragment size). This large fragment size may lead to much wasted space on file systems that contain many small files. .Sh SEE ALSO .Xr fdformat 1 , .Xr geom 4 , .Xr disktab 5 , .Xr fs 5 , .Xr bsdlabel 8 , .Xr camcontrol 8 , .Xr dump 8 , .Xr dumpfs 8 , .Xr fsck 8 , .Xr gjournal 8 , .Xr growfs 8 , +.Xr gvinum 8 , .Xr makefs 8 , .Xr mount 8 , -.Xr tunefs 8 , -.Xr gvinum 8 +.Xr tunefs 8 .Rs .%A M. McKusick .%A W. Joy .%A S. Leffler .%A R. Fabry .%T A Fast File System for UNIX .%J ACM Transactions on Computer Systems 2 .%V 3 .%P pp 181-197 .%D August 1984 .%O (reprinted in the BSD System Manager's Manual) .Re .Sh HISTORY The .Nm utility appeared in .Bx 4.2 .