2
3#
4# This is an example that shows how to send ASCII formatted control
5# messages to a node using ngctl(8).
6#
7# What we will do here create a divert(4) tap. This simply dumps
8# out all packets diverted by some ipfw(8) divert rule to the console.
9#
10# Lines that begin with ``$'' (shell prompt) or ``+'' (ngctl prompt)
11# indicate user input
12#
13
14# First, start up ngctl in interactive mode:
15
16 $ ngctl
17 Available commands:
18 connect Connects hook <peerhook> of the node at <relpath> to <hook>
19 debug Get/set debugging verbosity level
20 help Show command summary or get more help on a specific command
21 list Show information about all nodes
22 mkpeer Create and connect a new node to the node at "path"
23 msg Send a netgraph control message to the node at "path"
24 name Assign name <name> to the node at <path>
25 read Read and execute commands from a file
26 rmhook Disconnect hook "hook" of the node at "path"
27 show Show information about the node at <path>
28 shutdown Shutdown the node at <path>
29 status Get human readable status information from the node at <path>
30 types Show information about all installed node types
31 quit Exit program
32 +
33
| 2
3#
4# This is an example that shows how to send ASCII formatted control
5# messages to a node using ngctl(8).
6#
7# What we will do here create a divert(4) tap. This simply dumps
8# out all packets diverted by some ipfw(8) divert rule to the console.
9#
10# Lines that begin with ``$'' (shell prompt) or ``+'' (ngctl prompt)
11# indicate user input
12#
13
14# First, start up ngctl in interactive mode:
15
16 $ ngctl
17 Available commands:
18 connect Connects hook <peerhook> of the node at <relpath> to <hook>
19 debug Get/set debugging verbosity level
20 help Show command summary or get more help on a specific command
21 list Show information about all nodes
22 mkpeer Create and connect a new node to the node at "path"
23 msg Send a netgraph control message to the node at "path"
24 name Assign name <name> to the node at <path>
25 read Read and execute commands from a file
26 rmhook Disconnect hook "hook" of the node at "path"
27 show Show information about the node at <path>
28 shutdown Shutdown the node at <path>
29 status Get human readable status information from the node at <path>
30 types Show information about all installed node types
31 quit Exit program
32 +
33
|
35# of type SOCK_RAW, and protocol IPPROTO_DIVERT:
36
37 + mkpeer ksocket foo inet/raw/divert
38
39# Note that ``foo'' is the hook name on the socket node, which can be
40# anything. The ``inet/raw/divert'' is the hook name on the ksocket
41# node, which tells it what kind of socket to create.
42
43# Lets give our ksocket node a global name. How about ``fred'':
44
45 + name foo fred
46
47# Note that we used ngctl's ``name'' command to do this. However,
48# the following manually constructed netgraph message would have
49# acomplished the exact same thing:
50
51 + msg foo name { name="fred" }
52
53# Here we are using the ASCII <-> binary control message conversion
54# routines. ngctl does this for us automatically when we use the
55# ``msg'' command.
56
57# Now lets bind the socket associated with the ksocket node to a port
58# supplied by the system. We do this by sending the ksocket node a
59# ``bind'' control message. Again, ngctl does the conversion of the
60# control message from ASCII to binary behind the scenes.
61
62 + msg fred: bind inet/192.168.1.1
63
64# The ksocket accepts arbitrary sockaddr structures, but also has
65# special support for the PF_LOCAL and PF_INET protocol families.
66# That is why we can specify the struct sockaddr argument to the
67# ``bind'' command as ``inet/192.168.1.1'' (since we didn't specify
68# a port number, it's assumed to be zero). We could have also
69# relied on the generic sockaddr syntax and instead said this:
70
71 + msg fred: bind { family=2 len=16 data=[ 2=192 168 1 1 ] }
72
73# This is what you would have to do for protocol families other
74# that PF_INET and PF_LOCAL, at least until special handling for
75# new ones is added.
76
77# The reason for the ``2=192'' is to skip the two byte IP port number,
78# which causes it to be set to zero, the default value for integral
79# types when parsing. Now since we didn't ask for a specific port
80# number, we need to do a ``getname'' to see what port number we got:
81
82 + msg fred: getname
83 Rec'd response "getname" (5) from "fred:":
84 Args: inet/192.168.1.1:1029
85
86# As soon as we sent the message, we got back a response. Here
87# ngctl is telling us that it received a control message with the
88# NGF_RESP (response) flag set, the reponse was to a prior ``getname''
89# control message, that the originator was the node addressable
90# as ``fred:''. The message arguments field is then displayed to
91# us in its ASCII form. In this case, what we get back is a struct
92# sockaddr, and there we see that our port number is 1029.
93
94# So now let's add the ipfw divert rule for whatever packets we
95# want to see. How about anything from 192.168.1.129.
96
97 + ^Z
98 Suspended
99 $ ipfw add 100 divert 1029 ip from 192.168.1.129 to any
100 00100 divert 1029 ip from 192.168.1.129 to any
101 $ fg
102
103# Now watch what happens when we try to ping from that machine:
104
105 +
106 Rec'd data packet on hook "foo":
107 0000: 45 00 00 3c 57 00 00 00 20 01 bf ee c0 a8 01 81 E..<W... .......
108 0010: c0 a8 01 01 08 00 49 5c 03 00 01 00 61 62 63 64 ......I\....abcd
109 0020: 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 71 72 73 74 efghijklmnopqrst
110 0030: 75 76 77 61 62 63 64 65 66 67 68 69 uvwabcdefghi
111 +
112 Rec'd data packet on hook "foo":
113 0000: 45 00 00 3c 58 00 00 00 20 01 be ee c0 a8 01 81 E..<X... .......
114 0010: c0 a8 01 01 08 00 48 5c 03 00 02 00 61 62 63 64 ......H\....abcd
115 0020: 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 71 72 73 74 efghijklmnopqrst
116 0030: 75 76 77 61 62 63 64 65 66 67 68 69 uvwabcdefghi
117 +
118 Rec'd data packet on hook "foo":
119 0000: 45 00 00 3c 59 00 00 00 20 01 bd ee c0 a8 01 81 E..<Y... .......
120 0010: c0 a8 01 01 08 00 47 5c 03 00 03 00 61 62 63 64 ......G\....abcd
121 0020: 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 71 72 73 74 efghijklmnopqrst
122 0030: 75 76 77 61 62 63 64 65 66 67 68 69 uvwabcdefghi
123 +
124
125# So we're seeing the output from the ksocket socket appear on the ``foo''
126# hook of ngctl's socket node. Since the packets are getting diverted,
127# the 192.168.1.129 machine doesn't see any response from us.
128
129# Of course, any type of socket can be used, even TCP:
130
131 + mkpeer ksocket bar inet/stream/tcp
132 + msg bar connect inet/192.168.1.33:13
133 ngctl: send msg: Operation now in progress
134 +
135 Rec'd data packet on hook "foo":
136 0000: 4d 6f 6e 20 4e 6f 76 20 32 39 20 31 37 3a 34 38 Mon Nov 29 17:48
137 0010: 3a 33 37 20 31 39 39 39 0d 0a :37 1999..
138 +
139
140# Or, UNIX domain:
141
142 + mkpeer ksocket bar local/stream/0
143 + msg bar bind local/"/tmp/bar.socket"
144 +
145
146# Here's an example of a more complicated ASCII control message argument.
147# If you look in /sys/netgraph/ng_message.h, you will see that a node
148# responds to a NGM_LISTHOOKS with a struct hooklist, which contains
149# an array of struct linkinfo:
150#
151# /* Structure used for NGM_LISTHOOKS */
152# struct linkinfo {
153# char ourhook[NG_HOOKLEN + 1]; /* hook name */
154# char peerhook[NG_HOOKLEN + 1]; /* peer hook */
155# struct nodeinfo nodeinfo;
156# };
157#
158# struct hooklist {
159# struct nodeinfo nodeinfo; /* node information */
160# struct linkinfo link[0]; /* info about each hook */
161# };
162#
163# By sending a node the ``listhooks'' command using ngctl, we can see
164# this structure in ASCII form (lines wrapped for readability):
165
166 + msg bar bind local/"/tmp/bar.socket"
167 + msg bar listhooks
168 Rec'd response "listhooks" (7) from "bar":
169 Args: { nodeinfo={ type="ksocket" id=9 hooks=1 }
170 linkinfo=[ { ourhook="local/stream/0" peerhook="bar"
171 nodeinfo={ name="ngctl1327" type="socket" id=8 hooks=1 } } ] }
172
173
| 35# of type SOCK_RAW, and protocol IPPROTO_DIVERT:
36
37 + mkpeer ksocket foo inet/raw/divert
38
39# Note that ``foo'' is the hook name on the socket node, which can be
40# anything. The ``inet/raw/divert'' is the hook name on the ksocket
41# node, which tells it what kind of socket to create.
42
43# Lets give our ksocket node a global name. How about ``fred'':
44
45 + name foo fred
46
47# Note that we used ngctl's ``name'' command to do this. However,
48# the following manually constructed netgraph message would have
49# acomplished the exact same thing:
50
51 + msg foo name { name="fred" }
52
53# Here we are using the ASCII <-> binary control message conversion
54# routines. ngctl does this for us automatically when we use the
55# ``msg'' command.
56
57# Now lets bind the socket associated with the ksocket node to a port
58# supplied by the system. We do this by sending the ksocket node a
59# ``bind'' control message. Again, ngctl does the conversion of the
60# control message from ASCII to binary behind the scenes.
61
62 + msg fred: bind inet/192.168.1.1
63
64# The ksocket accepts arbitrary sockaddr structures, but also has
65# special support for the PF_LOCAL and PF_INET protocol families.
66# That is why we can specify the struct sockaddr argument to the
67# ``bind'' command as ``inet/192.168.1.1'' (since we didn't specify
68# a port number, it's assumed to be zero). We could have also
69# relied on the generic sockaddr syntax and instead said this:
70
71 + msg fred: bind { family=2 len=16 data=[ 2=192 168 1 1 ] }
72
73# This is what you would have to do for protocol families other
74# that PF_INET and PF_LOCAL, at least until special handling for
75# new ones is added.
76
77# The reason for the ``2=192'' is to skip the two byte IP port number,
78# which causes it to be set to zero, the default value for integral
79# types when parsing. Now since we didn't ask for a specific port
80# number, we need to do a ``getname'' to see what port number we got:
81
82 + msg fred: getname
83 Rec'd response "getname" (5) from "fred:":
84 Args: inet/192.168.1.1:1029
85
86# As soon as we sent the message, we got back a response. Here
87# ngctl is telling us that it received a control message with the
88# NGF_RESP (response) flag set, the reponse was to a prior ``getname''
89# control message, that the originator was the node addressable
90# as ``fred:''. The message arguments field is then displayed to
91# us in its ASCII form. In this case, what we get back is a struct
92# sockaddr, and there we see that our port number is 1029.
93
94# So now let's add the ipfw divert rule for whatever packets we
95# want to see. How about anything from 192.168.1.129.
96
97 + ^Z
98 Suspended
99 $ ipfw add 100 divert 1029 ip from 192.168.1.129 to any
100 00100 divert 1029 ip from 192.168.1.129 to any
101 $ fg
102
103# Now watch what happens when we try to ping from that machine:
104
105 +
106 Rec'd data packet on hook "foo":
107 0000: 45 00 00 3c 57 00 00 00 20 01 bf ee c0 a8 01 81 E..<W... .......
108 0010: c0 a8 01 01 08 00 49 5c 03 00 01 00 61 62 63 64 ......I\....abcd
109 0020: 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 71 72 73 74 efghijklmnopqrst
110 0030: 75 76 77 61 62 63 64 65 66 67 68 69 uvwabcdefghi
111 +
112 Rec'd data packet on hook "foo":
113 0000: 45 00 00 3c 58 00 00 00 20 01 be ee c0 a8 01 81 E..<X... .......
114 0010: c0 a8 01 01 08 00 48 5c 03 00 02 00 61 62 63 64 ......H\....abcd
115 0020: 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 71 72 73 74 efghijklmnopqrst
116 0030: 75 76 77 61 62 63 64 65 66 67 68 69 uvwabcdefghi
117 +
118 Rec'd data packet on hook "foo":
119 0000: 45 00 00 3c 59 00 00 00 20 01 bd ee c0 a8 01 81 E..<Y... .......
120 0010: c0 a8 01 01 08 00 47 5c 03 00 03 00 61 62 63 64 ......G\....abcd
121 0020: 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 71 72 73 74 efghijklmnopqrst
122 0030: 75 76 77 61 62 63 64 65 66 67 68 69 uvwabcdefghi
123 +
124
125# So we're seeing the output from the ksocket socket appear on the ``foo''
126# hook of ngctl's socket node. Since the packets are getting diverted,
127# the 192.168.1.129 machine doesn't see any response from us.
128
129# Of course, any type of socket can be used, even TCP:
130
131 + mkpeer ksocket bar inet/stream/tcp
132 + msg bar connect inet/192.168.1.33:13
133 ngctl: send msg: Operation now in progress
134 +
135 Rec'd data packet on hook "foo":
136 0000: 4d 6f 6e 20 4e 6f 76 20 32 39 20 31 37 3a 34 38 Mon Nov 29 17:48
137 0010: 3a 33 37 20 31 39 39 39 0d 0a :37 1999..
138 +
139
140# Or, UNIX domain:
141
142 + mkpeer ksocket bar local/stream/0
143 + msg bar bind local/"/tmp/bar.socket"
144 +
145
146# Here's an example of a more complicated ASCII control message argument.
147# If you look in /sys/netgraph/ng_message.h, you will see that a node
148# responds to a NGM_LISTHOOKS with a struct hooklist, which contains
149# an array of struct linkinfo:
150#
151# /* Structure used for NGM_LISTHOOKS */
152# struct linkinfo {
153# char ourhook[NG_HOOKLEN + 1]; /* hook name */
154# char peerhook[NG_HOOKLEN + 1]; /* peer hook */
155# struct nodeinfo nodeinfo;
156# };
157#
158# struct hooklist {
159# struct nodeinfo nodeinfo; /* node information */
160# struct linkinfo link[0]; /* info about each hook */
161# };
162#
163# By sending a node the ``listhooks'' command using ngctl, we can see
164# this structure in ASCII form (lines wrapped for readability):
165
166 + msg bar bind local/"/tmp/bar.socket"
167 + msg bar listhooks
168 Rec'd response "listhooks" (7) from "bar":
169 Args: { nodeinfo={ type="ksocket" id=9 hooks=1 }
170 linkinfo=[ { ourhook="local/stream/0" peerhook="bar"
171 nodeinfo={ name="ngctl1327" type="socket" id=8 hooks=1 } } ] }
172
173
|