| Both sides previous revision Previous revision Next revision | Previous revision |
| devd [2022/09/20 23:26] – Clean up KubilayKocak | devd [2022/09/26 22:19] (current) – Copyediting (4th and final installment for this run) PauAmma |
|---|
| The currently supported statements are as follows: | The currently supported statements are as follows: |
| |
| * ''%%attach%%'': When a device is plugged in and matches, an action is executed. | * ''%%attach%%'': When a device is plugged in and matches, perform an action. |
| * ''%%detach%%'': Contrary to the above. When a device is unplugged and matches, an action is executed. | * ''%%detach%%'': Reverse of the above. When a device is unplugged and matches, perform an action. |
| * ''%%nomatch%%'': This statements is triggered when a no device driver currently loaded in the kernel claims a new device. | * ''%%nomatch%%'': This statement is triggered when no device driver currently loaded in the kernel claims a new device. |
| * ''%%notify%%'': This statement can be the most useful in many circumstances, since it allows us to perform actions when the kernel sends an event to userspace. Normally, we can see this type of messages in ''%%/var/log/messages%%'' or by executing ''%%dmesg(8)%%''. | * ''%%notify%%'': This statement is very useful in many cases, since it allows us to perform actions when the kernel sends an event to userland. Normally, we can see this type of messages in ''%%/var/log/messages%%'' or by executing ''%%dmesg(8)%%''. |
| * ''%%options%%'': It specifies various options and parameters that we can use throughout the statements we create. | * ''%%options%%'': This sets various options and parameters that we can use throughout the statements we create. |
| |
| One way to understand the statements is to directly read ''%%/etc/devd.conf%%'' and review the above mentioned. It might also be useful to read what is in ''%%/etc/devd.conf%%'' and verify if a port we have installed, has created ''%%/usr/local/etc/devd%%'', that is a good starting point. | One way to understand the statements is to directly read ''%%/etc/devd.conf%%'' and review the above mentioned. It might also be useful to read ''%%/etc/devd.conf%%'' and verify if an installed port or package we have installed created ''%%/usr/local/etc/devd%%''; that is a good starting point. |
| |
| ==== Sub-Statements ==== | ==== Sub-Statements ==== |
| === options === | === options === |
| |
| * ''%%directory "/some/path";%%'': Specifies the directories to read and parse new statements with any file ending with the .conf extension. The default configuration file ''%%/etc/devd.conf%%'' already has two of these sub-statements in ''%%options%%'' to add directories ''%%/etc/devd%%'' and ''%%/usr/local/etc/devd%%''. | * ''%%directory "/some/path";%%'': Adds ''%%/some/path%%'' to the directories to read ''%%*.conf%%'' files from. The default configuration file ''%%/etc/devd.conf%%'' already has two of these sub-statements in ''%%options%%'' to add directories ''%%/etc/devd%%'' and ''%%/usr/local/etc/devd%%''. |
| * ''%%pid-file "/var/run/devd.pid";%%'': Specifies the file where the process ID is stored. Again, ''%%/etc/devd.conf%%'' has already one. | * ''%%pid-file "/var/run/devd.pid";%%'': Specifies the file where the process ID is stored. Again, ''%%/etc/devd.conf%%'' already has one. |
| * ''%%set regexp-name "(some|regexp)";%%'': Create a regular expression that can be used in some sub-statements. If it begin with ''%%!%%'', matches if a regular expression doesn't match. All regular expressions have an implicit ''%%$^%%'' around it. In ''%%/etc/devd.conf%%'' we can found some pre-defined regular expressions, such as ''%%scsi-controller-regex%%'' and ''%%wifi-driver-regex%%''. To use a regular expression in a sub-statement, the ''%%$%%'' sign can be used (e.g.: ''%%device-name "$wifi-driver-regex";%%''). | * ''%%set regexp-name "(some|regexp)";%%'': Create a regular expression that can be used in sub-statements later in the file. If it begins with ''%%!%%'', it matches if "(some|regexp)" doesn't match. All regular expressions have an implicit ''%%$^%%'' around them. In ''%%/etc/devd.conf%%'' we can find some pre-defined regular expressions, such as ''%%scsi-controller-regex%%'' and ''%%wifi-driver-regex%%''. To use a regular expression in a sub-statement, the ''%%$%%'' sign can be used (e.g.: ''%%device-name "$wifi-driver-regex";%%''). |
| |
| === attach y detach === | === attach and detach === |
| |
| * ''%%action "command";%%'': Execute a command. For example: ''%%/etc/pccard_ether $device-name start%%''. | * ''%%action "command";%%'': Execute a command. For example: ''%%/etc/pccard_ether $device-name start%%''. |
| * ''%%class "string";%%'': Shortcut to ''%%match "class" "string"%%''. | * ''%%class "string";%%'': Shortcut for ''%%match "class" "string"%%''. |
| * ''%%device-name "string";%%'': Shortcut to ''%%match "device-name" "string"%%''. A variable called ''%%$device-name%%'' can be used if the sub-statement matches. | * ''%%device-name "string";%%'': Shortcut for ''%%match "device-name" "string";%%''. A variable called `$device-name is set if the sub-statement matches. |
| * ''%%match "variable" "value";%%'': Matches the content of value against variable. For example, ''%%match "device-name" "$wifi-driver-regex";%%'' must match with the device name according to ''%%$wifi-driver-regex%%''. | * ''%%match "variable" "value";%%'': Matches the content of value against variable. For example, ''%%match "device-name" "$wifi-driver-regex";%%'' must match with the device name according to ''%%$wifi-driver-regex%%''. |
| * ''%%media-type "string";%%'': For network devices, ''%%media-type%%'' matches devices with the following types: | * ''%%media-type "string";%%'': For network devices, ''%%media-type%%'' matches devices with the following types (''%%devd.conf(5)%%'' in 12.3 and 13.1 still lists Tokenring and FDDI, which are no longer allowed): |
| * ''%%Ethernet%%'' | * ''%%Ethernet%%'' |
| * ''%%Tokenring%%'' | |
| * ''%%FDDI%%'' | |
| * ''%%802.11%%'' | * ''%%802.11%%'' |
| * ''%%ATM%%'' | * ''%%ATM%%'' |
| | * ''%%unknown%%'' |
| * ''%%subdevice "string";%%'': Shortcut to ''%%match "subdevice" "string";%%''. | * ''%%subdevice "string";%%'': Shortcut to ''%%match "subdevice" "string";%%''. |
| |
| === match === | === match === |
| |
| The following sub-statements have the same effect that the above sub-statement, so they will be mentioned without a description. The exception is ''%%action%%'' and ''%%match%%''. The former is to offer an useful example and the latter is because ''%%match%%'' is something different. | The following sub-statements have the same effect that the above sub-statement, so they will be mentioned without a description. The exception is ''%%action%%'' and ''%%match%%''. The first is to offer an useful example and the second is because ''%%match%%'' is something different. |
| |
| * ''%%action "command";%%'': Execute a command. For example, ''%%action "service dhclient quietstart $subsystem"%%''. Other useful example is when we need to use the ''%%$notify%%'' variable that is relative to the system and subsystem that triggered the event. | * ''%%action "command";%%'': Execute a command. For example, ''%%action "service dhclient quietstart $subsystem"%%''. Other useful example is when we need to use the ''%%$notify%%'' variable that is relative to the system and subsystem that triggered the event. |
| ==== Variables and the notify event ==== | ==== Variables and the notify event ==== |
| |
| There is a significant number of variables, systems, subsystems, types and notifications that can be used in statements that use the ''%%match%%'' sub-statement, but this article cannot cover because they can be found in ''%%devd.conf(5)%%''. See sections ''%%Variables that can be used with the match statement%%'' and ''%%Notify matching%%'' in ''%%devd.conf(5)%%''. | There are a lot of variables, systems, subsystems, types and notifications that can be used in statements that include a ''%%match%%'' sub-statement, but this article need not cover them because they can be found in ''%%devd.conf(5)%%''. See sections ''%%Variables that can be used with the match statement%%'' and ''%%Notify matching%%'' in ''%%devd.conf(5)%%''. |
| |
| ==== Comments ==== | ==== Comments ==== |
| // is a new comment, even though it is logically | // is a new comment, even though it is logically |
| // part of the previous comment. | // part of the previous comment. |
| | </code> |
| | |
| | The above may be written using perl-style comments: |
| | |
| | <code perl> |
| | # This is the start of a comment. The next line |
| | # is a new comment, even though it is logically |
| | # part of the previous comment. |
| </code> | </code> |
| |
| ==== Notes on Variable Expansion ==== | ==== Notes on Variable Expansion ==== |
| |
| To avoid problems with special characters in the shell, here's what happens, say, ''%%$foo%%'': | To avoid problems with shell special characters in action sub-statements, here's what happens to, say, ''%%$foo%%'': |
| |
| - The characters ''%%$'%%'' are inserted. | - The characters ''%%$'%%'' are inserted. |
| - The value of the foo variable is inserted into the buffer with all single quote characters prefixed by a backslash. | - The value of the foo variable is inserted into the buffer with all single quote characters prefixed by a backslash. |
| |
| In any context, these conditions are safe, but single quotes can cause unwanted effects. Suppose foo=meta and bar=var: | See sh(1) for what this construct means. In any context, these conditions are safe, but single quotes can cause unwanted effects. Suppose foo=meta and bar=var: |
| |
| <code> | <code> |
| </code> | </code> |
| |
| To understand what ''%%devd(8)%%'' does, we need to run it in the foreground instead of the background. Likewise, it is highly recommended to read ''%%/var/log/message%%'' and the output of ''%%dmesg(8)%%'' while writing and testing rules. | To understand what ''%%devd(8)%%'' does, we need to run it in the foreground instead of the background. Likewise, it is highly recommended to read ''%%/var/log/messages%%'' and the output of ''%%dmesg(8)%%'' while writing and testing rules. |
| |
| <code> | <code> |
| </code> | </code> |
| |
| The output is very descriptive. We see what ''%%devd(8)%%'' parses, which we can use for troubleshooting. It is highly recommended to run ''%%devd -d%%'' when we are creating a rule. | The output is very descriptive. We see what ''%%devd(8)%%'' parses, which we can use for troubleshooting. |
| |
| As mentioned, ''%%dmesg(8)%%'' and ''%%/var/log/messages%%'' can be our best friends. This is the output of ''%%dmesg(8)%%'' when a USB is connected: | As mentioned, ''%%dmesg(8)%%'' and ''%%/var/log/messages%%'' can be our best friends. This is the output of ''%%dmesg(8)%%'' when a USB key is connected: |
| |
| <code> | <code> |
| </code> | </code> |
| |
| When a devices matches ''%%umass0%%'', its name is printed using ''%%logger(1)%%''. We can see the message in ''%%/var/log/message%%'': | When a device matches ''%%umass0%%'', its name is printed using ''%%logger(1)%%''. We can see the message in ''%%/var/log/messages%%'': |
| |
| <code> | <code> |
| |
| <code> | <code> |
| $ diksinfo -s da0 | $ diskinfo -s da0 |
| 200515364102BCF2AC69 | 200515364102BCF2AC69 |
| </code> | </code> |
| </code> | </code> |
| |
| We are already to partition: | We are ready to partition: |
| |
| <code> | <code> |
| </code> | </code> |
| |
| Here the ''%%da0%%'' device with GPT is used and unique partition is added. That partition was formatted and mounted on ''%%/mnt%%'' to write a file called ''%%hello.txt%%''. Last, the partition is unmounted. | Here the ''%%da0%%'' device with GPT is used and a single partition is added. That partition is formatted and mounted on ''%%/mnt%%'' to write a file called ''%%hello.txt%%''. Last, the partition is unmounted. |
| |
| Unplug the device and plug in it again. The label is also useful for debugging, as it will print to the ''%%devd(8)%%'' output. | Unplug the device and plug it back in. The label is also useful for debugging, as it will be printed in the ''%%devd(8)%%'' output. |
| |
| <code> | <code> |
| </code> | </code> |
| |
| When we plug in our USB, the output of ''%%devd(8)%%'' is overwhelmingly large, so using a tool like ''%%screen(1)%%'' or ''%%tmux(1)%%'' is highly recommended, as either of them have a feature called //Copy Mode// that is useful for searching the output buffer. However, traditional tools like ''%%script(1)%%'' with a pager like ''%%less(1)%%'' or ''%%more(1)%%'' can be used for this purpose. | When we plug in our USB key, ''%%devd(8)%%'' output is very large, so using a tool like ''%%screen(1)%%'' or ''%%tmux(1)%%'' is highly recommended, as both of them have a feature called //Copy Mode// that is useful for searching the output buffer. However, traditional tools like ''%%script(1)%%'' with a pager like ''%%less(1)%%'' or ''%%more(1)%%'' can be used for this purpose. |
| |
| The idea is to search in the output of ''%%devd(8)%%'' to get the exact point of the event we need. When we've done that, we need to know if the parameters that ''%%devd(8)%%'' is using are the required ones. In this example, the following parameters are relevant: | The idea is to search ''%%devd(8)%%'' output to get the exact point of the event we need. When we've done that, we need to check whether the parameters that ''%%devd(8)%%'' is using are the required ones. In this example, the following parameters are relevant: |
| |
| <code> | <code> |
| </code> | </code> |
| |
| See the "[[#Variables_and_the_notify_event|Variables and the notify event]]" for more details on those parameters. | See "[[#Variables_and_the_notify_event|Variables and the notify event]]" for more details on those parameters. |
| |
| We need to modify ''%%usb_attach.conf%%'' with the parameters described above: | We need to modify ''%%usb_attach.conf%%'' with the parameters described above: |
| </code> | </code> |
| |
| We must increase the priority and add the subsystem for ''%%urndis(4)%%''. We also set ''%%dhclient(8)%%'' to ''%%action%%'' and when our device is plugged in, we should have Internet connection automatically. | We must increase the priority and add the subsystem for ''%%urndis(4)%%''. We also set ''%%dhclient(8)%%'' to ''%%action%%'' and when our device is plugged in, we should have an Internet connection automatically. |
| |
| <code> | <code> |