From ce8c7035746e21e09cf491be1fa1186714abd4b2 Mon Sep 17 00:00:00 2001 From: Aleksander Morgado Date: Tue, 17 Oct 2017 18:21:02 +0200 Subject: docs: include device filter policies/rules documentation --- docs/reference/api/ModemManager-overview.xml | 283 ++++++++++++++++++++++++++- 1 file changed, 277 insertions(+), 6 deletions(-) (limited to 'docs/reference/api') diff --git a/docs/reference/api/ModemManager-overview.xml b/docs/reference/api/ModemManager-overview.xml index fcd9d625..963c0df2 100644 --- a/docs/reference/api/ModemManager-overview.xml +++ b/docs/reference/api/ModemManager-overview.xml @@ -51,17 +51,16 @@ - - Modem detection and setup + + Modem detection
- Detection mechanisms + Builds with udev support ModemManager requires udev-powered Linux kernels in order to get notified of possible available Modems. udev will report each of the ports - found in the device, and ModemManager will probe each of the ports marked with - the ID_MM_CANDIDATE tag in udev. This includes both "tty" - and "net" ports. + found in the device, and ModemManager will consider for probing each of the ports + marked with the ID_MM_CANDIDATE tag in udev. Aditionally, users of RS232-based devices may need to request additional manual @@ -70,6 +69,278 @@ connected, not about the RS232 modem connected to the adapter, if any.
+ +
+ Builds without udev support + + When the udev daemon isn't available in the system, the + ReportKernelEvent + method in the + Manager interface + may be used to notify the ModemManager daemons of device addition and removals. + + + When udev support is disabled in the build, the ID_MM_CANDIDATE + tag and manual scan requests are still applicable. ModemManager has a built-in parser + of udev rule files that is enabled when udev itself isn't available. + +
+ + + + Modem filter + + + ModemManager will not probe all TTYs, NET and cdc-wdm ports found in the system, + as this may end up interfering e.g. with TTYs that have nothing to do with modem + devices. + + + The daemon comes with several predefined filter policies, each + of them composed of one or more filter rules. + + +
+ Filter rules + + The device filter in ModemManager defines the following independent filter rules. The + predefined filter policies are based on one or more of these predefined filter rules. + + + MM_FILTER_RULE_EXPLICIT_WHITELIST + + This filter allows users to manually tag devices and/or device ports with the + ID_MM_DEVICE_PROCESS udev tag. If the filter finds this tag, + the device and/or device ports will be automatically accepted and port probing + will be allowed. + + +$ sudo vim /lib/udev/rules.d/78-mm-whitelist-internal-modem.rules + ACTION!="add|change|move", GOTO="mm_whitelist_internal_modem_end" + ATTRS{idVendor}=="1199", ATTRS{idProduct}=="a001", ENV{ID_MM_DEVICE_PROCESS}="1" + LABEL="mm_whitelist_internal_modem_end" +// Apply new rules without reboot +$ sudo udevadm control --reload +$ sudo udevadm trigger + + + + MM_FILTER_RULE_VIRTUAL + + This filter will automatically flag as forbidden all ports exposed by virtual + devices, like the 'lo' network interface or the tty0, tty1... virtual terminals. + There is no reason to disable this filter, except for testing purposes. + + + + MM_FILTER_RULE_NET + + This filter will automatically flag as allowed all network ports exposed by + devices. Unless there is a will to explicitly forbid network ports, this filter + should always be enabled. + + + + MM_FILTER_RULE_CDC_WDM + + This filter will automatically flag as allowed all cdc-wdm ports exposed by + devices. Unless there is a will to explicitly forbid the cdc-wdm ports exposed + by qmi_wwan, cdc_mbim or huawei-cdc-ncm kernel drivers, this filter should always + be enabled. + + + + MM_FILTER_RULE_TTY, MM_FILTER_RULE_TTY_DEFAULT_ALLOWED and MM_FILTER_RULE_TTY_DEFAULT_FORBIDDEN + + If the MM_FILTER_RULE_TTY filter is disabled, no TTY port will be allowed. If this + filter is enabled, TTY ports will only be allowed if the TTY-specific filters (defined + next) allow it. + + + The MM_FILTER_RULE_TTY_DEFAULT_ALLOWED and MM_FILTER_RULE_TTY_DEFAULT_FORBIDDEN rules allow + defining what happens when a TTY port isn't explicitly forbidden or accepted by any of + the TTY-specific filters. When MM_FILTER_RULE_TTY is enabled, one of these other two options + must be set. + + + + MM_FILTER_RULE_TTY_BLACKLIST + + This filter will not allow probing any of the devices flagged as + ID_MM_DEVICE_IGNORE, like the ones in the default blacklist + shipped by ModemManager. + + + + MM_FILTER_RULE_TTY_MANUAL_SCAN_ONLY + + This filter will not allow automatic probing any of the devices flagged as + ID_MM_DEVICE_MANUAL_SCAN_ONLY, like the ones in the default + USB serial adapters greylist shipped by ModemManager. Devices flagged like + this will only be probed when a manual scan is requested via the + ScanDevices + method. + + + + MM_FILTER_RULE_TTY_PLATFORM_DRIVER + + If this filter is enabled, all platform TTY ports not explicitly flagged with the + ID_MM_PLATFORM_DRIVER_PROBE will be forbidden. If the flag + is found in a platform TTY port, port probing will be allowed directly. + + + Note that this filter is obsoleted by the more generic MM_FILTER_RULE_EXPLICIT_WHITELIST + filter. It is maintained for backwards compatibility with older ModemManager versions. + + + + MM_FILTER_RULE_TTY_DRIVER + + If this filter is enabled, all TTY ports managed by modem-specific kernel drivers will be + allowed automatically. + + + + FILTER_RULE_TTY_ACM_INTERFACE + + If this filter is enabled, all TTY ports managed by the cdc-acm kernel driver with + class=2/subclass=2/protocol=1 (AT command capable ttyACM port) will be allowed + automatically. + + + + MM_FILTER_RULE_TTY_WITH_NET + + If this filter is enabled, all TTY ports for devices that also expose a network + interface port will be allowed automatically. + + + + +
+ +
+ Filter policies + + + The predefined filter policies are: + + + Whitelist only + + This is a policy where only the MM_FILTER_RULE_EXPLICIT_WHITELIST rule is enabled. + + # /usr/sbin/ModemManager --filter-policy=WHITELIST-ONLY + + + Default + + This is a policy where the following rules are enabled: + + MM_FILTER_RULE_EXPLICIT_WHITELIST + MM_FILTER_RULE_VIRTUAL + MM_FILTER_RULE_NET + MM_FILTER_RULE_CDC_WDM + MM_FILTER_RULE_TTY + MM_FILTER_RULE_TTY_BLACKLIST + MM_FILTER_RULE_TTY_MANUAL_SCAN_ONLY + MM_FILTER_RULE_TTY_PLATFORM_DRIVER + MM_FILTER_RULE_TTY_DEFAULT_ALLOWED + + + + This policy is the default one when a different one not explicitly + selected, and is equivalent to the way ModemManager has worked in previous + releases. This policy is the least restrictive one, and will end up + allowing port probing of all TTYs not explicitly blacklisted in one way + or another. + + # /usr/sbin/ModemManager --filter-policy=DEFAULT + + + Strict + + This is a policy where the following rules are enabled: + + MM_FILTER_RULE_EXPLICIT_WHITELIST + MM_FILTER_RULE_VIRTUAL + MM_FILTER_RULE_NET + MM_FILTER_RULE_CDC_WDM + MM_FILTER_RULE_TTY + MM_FILTER_RULE_TTY_PLATFORM_DRIVER + MM_FILTER_RULE_TTY_DRIVER + MM_FILTER_RULE_TTY_ACM_INTERFACE + MM_FILTER_RULE_TTY_WITH_NET + MM_FILTER_RULE_TTY_DEFAULT_FORBIDDEN + + + + This policy is stricter than the default one, as by default all TTYs are + forbidden except for the ones explicitly allowed by one of the TTY-specific + rules. Distributions or users should use this policy if they don't want + ModemManager to mess around with TTY ports that may not be exposed by + actual modems. + + # /usr/sbin/ModemManager --filter-policy=STRICT + + + Paranoid + + This policy is a mix of the Default and Strict ones: + + MM_FILTER_RULE_EXPLICIT_WHITELIST + MM_FILTER_RULE_VIRTUAL + MM_FILTER_RULE_NET + MM_FILTER_RULE_CDC_WDM + MM_FILTER_RULE_TTY + MM_FILTER_RULE_TTY_BLACKLIST + MM_FILTER_RULE_TTY_MANUAL_SCAN_ONLY + MM_FILTER_RULE_TTY_PLATFORM_DRIVER + MM_FILTER_RULE_TTY_DRIVER + MM_FILTER_RULE_TTY_ACM_INTERFACE + MM_FILTER_RULE_TTY_WITH_NET + MM_FILTER_RULE_TTY_DEFAULT_FORBIDDEN + + + + This policy is equivalent to the Strict policy, but where the ModemManager + provided blacklist and manual scan only greylist are also used. It is not + recommended to use this option in normal setups as the blacklists may be + obsoleted in future ModemManager versions (in favor of using the Strict + policy as default). + + # /usr/sbin/ModemManager --filter-policy=PARANOID + + + + Custom + + Any of the previously defined predefined policies may be modified rule per rule + by explicitly enabling or disabling rules via environment variables. + + + E.g. this would launch ModemManager with the Default filter policy but with all + net and cdc-wdm ports forbidden completely: + +# MM_FILTER_RULE_NET=0 \ + MM_FILTER_RULE_CDC_WDM=0 \ + /usr/sbin/ModemManager --filter-policy=DEFAULT + + + E.g. this would launch ModemManager with the Whitelist-only filter policy but also + explicitly allowing all net and cdc-wdm ports. Note that in this case, all virtual + net ports (e.g. 'lo') are also being allowed. + +# MM_FILTER_RULE_NET=1 \ + MM_FILTER_RULE_CDC_WDM=1 \ + /usr/sbin/ModemManager --filter-policy=WHITELIST-ONLY + + + + + +
-- cgit v1.2.3-70-g09d2