1.\" Copyright (c) 1996-1999 Whistle Communications, Inc. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, use and 5.\" redistribution of this software, in source or object code forms, with or 6.\" without modifications are expressly permitted by Whistle Communications; 7.\" provided, however, that: 8.\" 1. Any and all reproductions of the source or object code must include the 9.\" copyright notice above and the following disclaimer of warranties; and 10.\" 2. No rights are granted, in any manner or form, to use Whistle 11.\" Communications, Inc. trademarks, including the mark "WHISTLE 12.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as 13.\" such appears in the above copyright notice or in the software. 14.\" 15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND 16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO 17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, 18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. 20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY 21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS 22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. 23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES 24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING 25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR 27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY 31.\" OF SUCH DAMAGE. 32.\" 33.\" Author: Archie Cobbs <archie@FreeBSD.org> 34.\" 35.\" $FreeBSD$ 36.\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $ 37.\" 38.Dd July 27, 2004 39.Dt NG_PPPOE 4 40.Os 41.Sh NAME 42.Nm ng_pppoe 43.Nd RFC 2516 PPPoE protocol netgraph node type 44.Sh SYNOPSIS 45.In net/ethernet.h 46.In netgraph/ng_pppoe.h 47.Sh DESCRIPTION 48The 49.Nm pppoe 50node type performs the PPPoE protocol. 51It is used in conjunction with the 52.Xr netgraph 4 53extensions to the Ethernet framework to divert and inject Ethernet packets 54to and from a PPP agent (which is not specified). 55.Pp 56The 57.Dv NGM_PPPOE_GET_STATUS 58control message can be used at any time to query the current status 59of the PPPoE module. 60The only statistics presently available are the 61total packet counts for input and output. 62This node does not yet support 63the 64.Dv NGM_TEXT_STATUS 65control message. 66.Sh HOOKS 67This node type supports the following hooks: 68.Pp 69.Bl -tag -width [unspecified] 70.It Dv ethernet 71The hook that should normally be connected to an Ethernet node. 72.It Dv debug 73Presently no use. 74.It Dv [unspecified] 75Any other name is assumed to be a session hook that will be connected to 76a PPP client agent, or a PPP server agent. 77.El 78.Sh CONTROL MESSAGES 79This node type supports the generic control messages, plus the following: 80.Bl -tag -width 3n 81.It Dv NGM_PPPOE_GET_STATUS 82This command returns status information in a 83.Dv "struct ngpppoestat" : 84.Bd -literal -offset 4n 85struct ngpppoestat { 86 u_int packets_in; /* packets in from Ethernet */ 87 u_int packets_out; /* packets out towards Ethernet */ 88}; 89.Ed 90.It Dv NGM_TEXT_STATUS 91This generic message returns is a human-readable version of the node status. 92(not yet) 93.It Dv NGM_PPPOE_CONNECT 94Tell a nominated newly created hook that it's session should enter 95the state machine in a manner to become a client. 96It must be newly created and 97a service name can be given as an argument. 98It is legal to specify a zero length service name. 99This is common on some DSL setups. 100A session request packet will be broadcast on the Ethernet. 101This command uses the 102.Dv ngpppoe_init_data 103structure shown below. 104.It Dv NGM_PPPOE_LISTEN 105Tell a nominated newly created hook that it's session should enter 106the state machine in a manner to become a server listener. 107The argument 108given is the name of the service to listen on behalf of 109a zero length service length will match all requests for service. 110A matching service request 111packet will be passed unmodified back to the process responsible 112for starting the service. 113It can then examine it and pass it on to 114the session that is started to answer the request. 115This command uses the 116.Dv ngpppoe_init_data 117structure shown below. 118.It Dv NGM_PPPOE_OFFER 119Tell a nominated newly created hook that it's session should enter 120the state machine in a manner to become a server. 121The argument given is the name of the service to offer. 122A zero length service 123is legal. 124The State machine will progress to a state where it will await 125a request packet to be forwarded to it from the startup server, 126which in turn probably received it from a LISTEN mode hook ( see above). 127This is so 128that information that is required for the session that is embedded in 129the original session request packet, is made available to the state machine 130that eventually answers the request. 131When the Session request packet is 132received, the session negotiation will proceed. 133This command uses the 134.Dv ngpppoe_init_data 135structure shown below. 136.El 137.Pp 138The three commands above use a common data structure: 139.Bd -literal -offset 4n 140struct ngpppoe_init_data { 141 char hook[NG_HOOKSIZ]; /* hook to monitor on */ 142 u_int16_t data_len; /* service name length */ 143 char data[0]; /* init data goes here */ 144}; 145.Ed 146.Bl -tag -width 3n 147.It Dv NGM_PPPOE_SUCCESS 148This command is sent to the node that started this session with one of the 149above messages, and reports a state change. 150This message reports successful Session negotiation. 151It uses the structure shown below, and 152reports back the hook name corresponding to the successful session. 153.It Dv NGM_NGM_PPPOE_FAIL 154This command is sent to the node that started this session with one of the 155above messages, and reports a state change. 156This message reports failed Session negotiation. 157It uses the structure shown below, and 158reports back the hook name corresponding to the failed session. 159The hook will probably have been removed immediately after sending this message 160.It Dv NGM_NGM_PPPOE_CLOSE 161This command is sent to the node that started this session with one of the 162above messages, and reports a state change. 163This message reports a request to close a session. 164It uses the structure shown below, and 165reports back the hook name corresponding to the closed session. 166The hook will probably have been removed immediately after sending this 167message. 168At present this message is not yet used and a 'failed' message 169will be received at closure instead. 170.It Dv NGM_PPPOE_ACNAME 171This command is sent to the node that started this session with one of the 172above messages, and reports the Access Concentrator Name. 173.El 174.Pp 175The four commands above use a common data structure: 176.Bd -literal -offset 4n 177struct ngpppoe_sts { 178 char hook[NG_HOOKSIZ]; /* hook associated with event session */ 179}; 180.Ed 181.Bl -tag -width 3n 182.It Dv NGM_PPPOE_GETMODE 183The 184.Nm 185node can operate in two different modes: 186standard mode described in RFC 2516, and in a non-standard mode compatible 187with equipment from 3Com. 188When 189.Nm 190is a client node, it initiates a session using the configured mode. 191In server mode 192.Nm 193supports both modes simultaneously. 194This message returns the currently configured mode as a string. 195.Tn ASCII 196form of this message is 197.Qq Li pppoe_getmode . 198.It Dv NGM_PPPOE_SETMODE 199Configure node to the specified mode. 200The string argument is required. 201.Tn ASCII 202form of this message is 203.Qq Li pppoe_setmode . 204For example, the following command will configure the node to initiate 205the next session in the proprietary 3Com mode: 206.Pp 207.Dl ngctl msg fxp0:orphans pppoe_setmode "3Com" 208.El 209.Sh SHUTDOWN 210This node shuts down upon receipt of a 211.Dv NGM_SHUTDOWN 212control message, when all session have been disconnected or when the 213.Dv ethernet 214hook is disconnected. 215.Sh SYSCTL VARIABLES 216The variable 217.Va net.graph.nonstandard_pppoe 218is a deprecated way to set 219.Nm 220client mode. 221Consider using 222.Dv NGM_PPPOE_SETMODE 223or an appropriate option in your client software instead. 224.Sh EXAMPLES 225The following code uses 226.Dv libnetgraph 227to set up a 228.Nm 229node and connect it to both a socket node and an Ethernet node. 230It can handle the case of when a 231.Nm 232node is already attached to the Ethernet. 233It then starts a client session. 234.Bd -literal 235#include <stdio.h> 236#include <stdlib.h> 237#include <string.h> 238#include <ctype.h> 239#include <unistd.h> 240#include <sysexits.h> 241#include <errno.h> 242#include <err.h> 243 244#include <sys/types.h> 245#include <sys/socket.h> 246#include <sys/select.h> 247#include <net/ethernet.h> 248 249#include <netgraph.h> 250#include <netgraph/ng_ether.h> 251#include <netgraph/ng_pppoe.h> 252#include <netgraph/ng_socket.h> 253static int setup(char *ethername, char *service, char *sessname, 254 int *dfd, int *cfd); 255 256int 257main() 258{ 259 int fd1, fd2; 260 setup("xl0", NULL, "fred", &fd1, &fd2); 261 sleep (30); 262} 263 264static int 265setup(char *ethername, char *service, char *sessname, 266 int *dfd, int *cfd) 267{ 268 struct ngm_connect ngc; /* connect */ 269 struct ngm_mkpeer mkp; /* mkpeer */ 270 /******** nodeinfo stuff **********/ 271 u_char rbuf[2 * 1024]; 272 struct ng_mesg *const resp = (struct ng_mesg *) rbuf; 273 struct hooklist *const hlist 274 = (struct hooklist *) resp->data; 275 struct nodeinfo *const ninfo = &hlist->nodeinfo; 276 int ch, no_hooks = 0; 277 struct linkinfo *link; 278 struct nodeinfo *peer; 279 /****message to connect PPPoE session*****/ 280 struct { 281 struct ngpppoe_init_data idata; 282 char service[100]; 283 } message; 284 /********tracking our little graph ********/ 285 char path[100]; 286 char source_ID[NG_NODESIZ]; 287 char pppoe_node_name[100]; 288 int k; 289 290 /* 291 * Create the data and control sockets 292 */ 293 if (NgMkSockNode(NULL, cfd, dfd) < 0) { 294 return (errno); 295 } 296 /* 297 * find the ether node of the name requested by asking it for 298 * it's inquiry information. 299 */ 300 if (strlen(ethername) > 16) 301 return (EINVAL); 302 sprintf(path, "%s:", ethername); 303 if (NgSendMsg(*cfd, path, NGM_GENERIC_COOKIE, 304 NGM_LISTHOOKS, NULL, 0) < 0) { 305 return (errno); 306 } 307 /* 308 * the command was accepted so it exists. Await the reply (It's 309 * almost certainly already waiting). 310 */ 311 if (NgRecvMsg(*cfd, resp, sizeof(rbuf), NULL) < 0) { 312 return (errno); 313 } 314 /** 315 * The following is available about the node: 316 * ninfo->name (string) 317 * ninfo->type (string) 318 * ninfo->id (u_int32_t) 319 * ninfo->hooks (u_int32_t) (count of hooks) 320 * check it is the correct type. and get it's ID for use 321 * with mkpeer later. 322 */ 323 if (strncmp(ninfo->type, NG_ETHER_NODE_TYPE, 324 strlen(NG_ETHER_NODE_TYPE)) != 0) { 325 return (EPROTOTYPE); 326 } 327 sprintf(source_ID, "[%08x]:", ninfo->id); 328 329 /* 330 * look for a hook already attached. 331 */ 332 for (k = 0; k < ninfo->hooks; k++) { 333 /** 334 * The following are available about each hook. 335 * link->ourhook (string) 336 * link->peerhook (string) 337 * peer->name (string) 338 * peer->type (string) 339 * peer->id (u_int32_t) 340 * peer->hooks (u_int32_t) 341 */ 342 link = &hlist->link[k]; 343 peer = &hlist->link[k].nodeinfo; 344 345 /* Ignore debug hooks */ 346 if (strcmp("debug", link->ourhook) == 0) 347 continue; 348 349 /* If the orphans hook is attached, use that */ 350 if (strcmp(NG_ETHER_HOOK_ORPHAN, 351 link->ourhook) == 0) { 352 break; 353 } 354 /* the other option is the 'divert' hook */ 355 if (strcmp("NG_ETHER_HOOK_DIVERT", 356 link->ourhook) == 0) { 357 break; 358 } 359 } 360 361 /* 362 * See if we found a hook there. 363 */ 364 if (k < ninfo->hooks) { 365 if (strcmp(peer->type, NG_PPPOE_NODE_TYPE) == 0) { 366 /* 367 * If it's a type PPPoE, we skip making one 368 * ourself, but we continue, using 369 * the existing one. 370 */ 371 sprintf(pppoe_node_name, "[%08x]:", peer->id); 372 } else { 373 /* 374 * There is already someone hogging the data, 375 * return an error. Some day we'll try 376 * daisy-chaining.. 377 */ 378 return (EBUSY); 379 } 380 } else { 381 382 /* 383 * Try make a node of type PPPoE against node "ID" 384 * On hook NG_ETHER_HOOK_ORPHAN. 385 */ 386 snprintf(mkp.type, sizeof(mkp.type), 387 "%s", NG_PPPOE_NODE_TYPE); 388 snprintf(mkp.ourhook, sizeof(mkp.ourhook), 389 "%s", NG_ETHER_HOOK_ORPHAN); 390 snprintf(mkp.peerhook, sizeof(mkp.peerhook), 391 "%s", NG_PPPOE_HOOK_ETHERNET); 392 /* Send message */ 393 if (NgSendMsg(*cfd, source_ID, NGM_GENERIC_COOKIE, 394 NGM_MKPEER, &mkp, sizeof(mkp)) < 0) { 395 return (errno); 396 } 397 /* 398 * Work out a name for the new node. 399 */ 400 sprintf(pppoe_node_name, "%s:%s", 401 source_ID, NG_ETHER_HOOK_ORPHAN); 402 } 403 /* 404 * We now have a PPPoE node attached to the Ethernet 405 * card. The Ethernet is addressed as ethername: The PPPoE 406 * node is addressed as pppoe_node_name: attach to it. 407 * Connect socket node to specified node Use the same hook 408 * name on both ends of the link. 409 */ 410 snprintf(ngc.path, sizeof(ngc.path), "%s", pppoe_node_name); 411 snprintf(ngc.ourhook, sizeof(ngc.ourhook), "%s", sessname); 412 snprintf(ngc.peerhook, sizeof(ngc.peerhook), "%s", sessname); 413 414 if (NgSendMsg(*cfd, ".:", NGM_GENERIC_COOKIE, 415 NGM_CONNECT, &ngc, sizeof(ngc)) < 0) { 416 return (errno); 417 } 418 419#ifdef NONSTANDARD 420 /* 421 * In some cases we are speaking to 3Com hardware, so 422 * configure node to non-standard mode. 423 */ 424 if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, 425 NGM_PPPOE_SETMODE, NG_PPPOE_NONSTANDARD, 426 strlen(NG_PPPOE_NONSTANDARD) + 1) == -1) { 427 return (errno); 428 } 429#endif 430 431 /* 432 * Send it a message telling it to start up. 433 */ 434 bzero(&message, sizeof(message)); 435 snprintf(message.idata.hook, sizeof(message.idata.hook), 436 "%s", sessname); 437 if (service == NULL) { 438 message.idata.data_len = 0; 439 } else { 440 snprintf(message.idata.data, 441 sizeof(message.idata.data), "%s", service); 442 message.idata.data_len = strlen(service); 443 } 444 /* Tell session/hook to start up as a client */ 445 if (NgSendMsg(*cfd, ngc.path, 446 NGM_PPPOE_COOKIE, NGM_PPPOE_CONNECT, &message.idata, 447 sizeof(message.idata) + message.idata.data_len) < 0) { 448 return (errno); 449 } 450 return (0); 451} 452.Ed 453.Sh SEE ALSO 454.Xr netgraph 3 , 455.Xr netgraph 4 , 456.Xr ng_ppp 4 , 457.Xr ng_socket 4 , 458.Xr ngctl 8 , 459.Xr ppp 8 460.Rs 461.%A L. Mamakos 462.%A K. Lidl 463.%A J. Evarts 464.%A D. Carrel 465.%A D. Simone 466.%A R. Wheeler 467.%T "A Method for transmitting PPP over Ethernet (PPPoE)" 468.%O RFC 2516 469.Re 470.Sh HISTORY 471The 472.Nm 473node type was implemented in 474.Fx 4.0 . 475.Sh AUTHORS 476.An Julian Elischer Aq julian@FreeBSD.org 477