Differential D9270 Diff 32487 share/man/man4/ng_pppoe.4

Changeset View

Standalone View

share/man/man4/ng_pppoe.4

	Show All 29 Lines
	.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY			.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
	.\" OF SUCH DAMAGE.			.\" OF SUCH DAMAGE.
	.\"			.\"
	.\" Author: Archie Cobbs <archie@FreeBSD.org>			.\" Author: Archie Cobbs <archie@FreeBSD.org>
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $			.\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $
	.\"			.\"
	.Dd September 15, 2015			.Dd April 4, 2017
	.Dt NG_PPPOE 4			.Dt NG_PPPOE 4
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm ng_pppoe			.Nm ng_pppoe
	.Nd RFC 2516 PPPoE protocol netgraph node type			.Nd RFC 2516 PPPoE protocol netgraph node type
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/types.h			.In sys/types.h
	.In net/ethernet.h			.In net/ethernet.h
	▲ Show 20 Lines • Show All 52 Lines • ▼ Show 20 Lines
	This generic message returns a human-readable version of the node status.			This generic message returns a human-readable version of the node status.
	(not yet)			(not yet)
	.It Dv NGM_PPPOE_CONNECT Pq Ic pppoe_connect			.It Dv NGM_PPPOE_CONNECT Pq Ic pppoe_connect
	Tell a nominated newly created hook that its session should enter			Tell a nominated newly created hook that its session should enter
	the state machine as a client.			the state machine as a client.
	It must be newly created and a service name can be given as an argument.			It must be newly created and a service name can be given as an argument.
	It is legal to specify a zero-length service name, this is common			It is legal to specify a zero-length service name, this is common
	on some DSL setups.			on some DSL setups.
	It is possible to request a connection to a specific			It is possible to request a connection to a specific access concentrator,
				wblockUnsubmitted Done Inline Actions "host uniq" should be capitalized or otherwise identified with markup. Since it's used below, just be consistent and say `Host-Uniq`. wblock: "host uniq" should be capitalized or otherwise identified with markup. Since it's used below…
				aleAuthorUnsubmitted Done Inline Actions Are you fine with lower case "access concentrator"? ale: Are you fine with lower case "access concentrator"?
	access concentrator by its name using the "AC-Name\\Service-Name" syntax.			and/or set a specific Host-Uniq tag, required by some Internet providers,
				wblockUnsubmitted Done Inline Actions The formatting looks odd, but is apparently meant to show that there is an optional AC-Name followed by double backslashes if present, followed by an optional Host-Uniq with a vertical bar if present. Does this render correctly? wblock: The formatting looks odd, but is apparently meant to show that there is an optional AC-Name…
				aleAuthorUnsubmitted Done Inline Actions The double backslash is just for man page escaping, it's actually a single backslash. Both AC-Name and Host-Uniq are optional, that's the reason for different separators. ale: The double backslash is just for man page escaping, it's actually a single backslash. Both AC…
	A session request packet will be broadcasted on the Ethernet.			using the
				.Qq Li [AC-Name\\][Host-Uniq\|]Service-Name
				julianUnsubmitted Done Inline Actions There are ways to set binary values. though this will do. I f we decide it's limiting, we can improve it. julian: There are ways to set binary values. though this will do. I f we decide it's limiting, we can…
				syntax.
				To set a binary Host-Uniq, it must be encoded as a hexadecimal lowercase
				string and prefixed with
				.Qq Li 0x ,
				for example
				wblockUnsubmitted Done Inline Actions Would prefer "like" or "for example" to exempli gratia here (see `igor -y ng_pppoe.4`), but if you want to stick with that, it should be "e.g.,". Yes, it's clunky. In this case, I prefer "like". wblock: Would prefer "like" or "for example" to exempli gratia here (see `igor -y ng_pppoe.4`), but if…
				.Qq Li 0x6d792d746167
				is equivalent to
				.Qq Li my-tag .
				A session request packet will be broadcast on the Ethernet.
				wblockUnsubmitted Done Inline Actions (Not yours, I know.) s/broadcasted/broadcast/ wblock: (Not yours, I know.) s/broadcasted/broadcast/
	This command uses the			This command uses the
	.Dv ngpppoe_init_data			.Dv ngpppoe_init_data
	structure shown below.			structure shown below.
				For example, this init data argument can be used to
				wblockUnsubmitted Done Inline Actions s/the following/this/ wblock: s/the following/this/
				connect to
				wblockUnsubmitted Done Inline Actions Markup could show these with out-of-band highlighting rather than quotes. But I'm not sure which markup to use. wblock: Markup could show these with out-of-band highlighting rather than quotes. But I'm not sure…
				aleAuthorUnsubmitted Done Inline Actions I'll make a few tries, .Sq might be a good choice ale: I'll make a few tries, .Sq might be a good choice
				.Qq Li my-isp
				service with
				.Qq Li my-host
				uniq tag, accepting only
				.Qq Li remote-ac
				as access concentrator:
				.Bd -literal -offset indent
				"remote-ac\\my-host\|my-isp"
				.Ed
	.It Dv NGM_PPPOE_LISTEN Pq Ic pppoe_listen			.It Dv NGM_PPPOE_LISTEN Pq Ic pppoe_listen
	Tell a nominated newly created hook that its session should enter			Tell a nominated newly created hook that its session should enter
	the state machine as a server listener.			the state machine as a server listener.
	The argument			The argument
	given is the name of the service to listen for.			given is the name of the service to listen for.
	A zero-length service name will match all requests for service.			A zero-length service name will match all requests for service.
	A matching service request			A matching service request
	packet will be passed unmodified back to the process responsible			packet will be passed unmodified back to the process responsible
	▲ Show 20 Lines • Show All 132 Lines • ▼ Show 20 Lines
	.Pp			.Pp
	Data structure returned to client is:			Data structure returned to client is:
	.Bd -literal -offset 4n			.Bd -literal -offset 4n
	struct ngpppoe_maxp {			struct ngpppoe_maxp {
	char hook[NG_HOOKSIZ];			char hook[NG_HOOKSIZ];
	uint16_t data;			uint16_t data;
	};			};
	.Ed			.Ed
				.It Dv NGM_PPPOE_SEND_HURL Pq Ic send_hurl
				Tell a nominated hook with an active session to send a PADM message with
				a HURL tag.
				The argument is the URL to be delivered to the client:
				wblockUnsubmitted Done Inline Actions Rewording: The argument is the URL to be delivered to the client: wblock: Rewording: ```The argument is the URL to be delivered to the client:```
				.Bd -literal -offset indent
				ngctl msg fxp0:orphans send_hurl '{ hook="myHook" data="http://example.net/cpe" }'
				.Ed
				.It Dv NGM_PPPOE_SEND_MOTM Pq Ic send_motm
				Tell a nominated hook with an active session to send a PADM message with
				a MOTM tag.
				The argument is the message to be delivered to the client:
				wblockUnsubmitted Done Inline Actions The argument is the message to be delivered to the client: wblock: ```The argument is the message to be delivered to the client:```
				.Bd -literal -offset indent
				ngctl msg fxp0:orphans send_motm '{ hook="myHook" data="Welcome aboard" }'
				.Ed
	.El			.El
				.Pp
				The two commands above use the same ngpppoe_init_data structure described
				above.
				.Bl -tag -width 3n
				.It Dv NGM_PPPOE_HURL
				This command is sent to the node that started this session when a PADM
				message with a HURL tag is received, and contains a URL that the host can
				wblockUnsubmitted Done Inline Actions "may" usually implies "you have permission", while "can" means "it is possible". So: message with a HURL tag is received, and contains a URL which the Host can Should Host be capitalized? wblock: "may" usually implies "you have permission", while "can" means "it is possible". So…
				aleAuthorUnsubmitted Done Inline Actions It's MAY in RFC 2119 meaning, but I'll change it to "can". I capitalized the Host to make it clearer what's the meaning of the H in HURL, but probably is not needed. ale: It's MAY in RFC 2119 meaning, but I'll change it to "can". I capitalized the Host to make it…
				pass to a web browser for presentation to the user.
				.It Dv NGM_PPPOE_MOTM
				This command is sent to the node that started this session when a PADM
				message with a MOTM tag is received, and contains a Message Of The
				Minute that the host can display to the user.
				wblockUnsubmitted Done Inline Actions As above: Minute which the Host can display to the user. wblock: As above: ```Minute which the Host can display to the user.```
				.El
				.Pp
				The two commands above use a common data structure:
				.Bd -literal -offset 4n
				struct ngpppoe_padm {
				char msg[PPPOE_PADM_VALUE_SIZE];
				};
				.Ed
	.Sh SHUTDOWN			.Sh SHUTDOWN
	This node shuts down upon receipt of a			This node shuts down upon receipt of a
	.Dv NGM_SHUTDOWN			.Dv NGM_SHUTDOWN
	control message, when all session have been disconnected or when the			control message, when all session have been disconnected or when the
	.Dv ethernet			.Dv ethernet
	hook is disconnected.			hook is disconnected.
	.Sh EXAMPLES			.Sh EXAMPLES
	The following code uses			The following code uses
	▲ Show 20 Lines • Show All 252 Lines • Show Last 20 Lines