From 960bcb6dfa29001941168790b9a5026294bd96c4 Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Mon, 16 Nov 2009 12:33:27 -0800 Subject: [PATCH] doc: document the IP4Config setting --- libnm-util/nm-setting-ip4-config.c | 192 +++++++++++++++++++++++++++-- 1 file changed, 181 insertions(+), 11 deletions(-) diff --git a/libnm-util/nm-setting-ip4-config.c b/libnm-util/nm-setting-ip4-config.c index c1fc1fc67f..02f1e63bd5 100644 --- a/libnm-util/nm-setting-ip4-config.c +++ b/libnm-util/nm-setting-ip4-config.c @@ -708,91 +708,261 @@ nm_setting_ip4_config_class_init (NMSettingIP4ConfigClass *setting_class) parent_class->verify = verify; /* Properties */ + /** + * NMSettingIP4Config:method: + * + * IPv4 configuration method. If 'auto' is specified then the appropriate + * automatic method (DHCP, PPP, etc) is used for the device and most other + * properties can be left unset. If 'link-local' is specified, then a + * link-local address in the 169.254/16 range will be assigned to the + * interface. If 'manual' is specified, static IP addressing is used and at + * least one IP address must be given in the 'addresses' property. If + * 'shared' is specified (indicating that this connection will provide + * network access to other computers) then the interface is assigned an + * address in the 10.42.x.1/24 range and a DHCP and forwarding DNS server + * are started, and the interface is NAT-ed to the current default network + * connection. This property must be set. + **/ g_object_class_install_property (object_class, PROP_METHOD, g_param_spec_string (NM_SETTING_IP4_CONFIG_METHOD, "Method", - "IP configuration method", + "IPv4 configuration method. If 'auto' is specified " + "then the appropriate automatic method (DHCP, PPP, " + "etc) is used for the device and most other " + "properties can be left unset. If 'link-local' " + "is specified, then a link-local address in the " + "169.254/16 range will be assigned to the " + "interface. If 'manual' is specified, static IP " + "addressing is used and at least one IP address " + "must be given in the 'addresses' property. If " + "'shared' is specified (indicating that this " + "connection will provide network access to other " + "computers) then the interface is assigned an " + "address in the 10.42.x.1/24 range and a DHCP and " + "forwarding DNS server are started, and the " + "interface is NAT-ed to the current default network " + "connection. This property must be set.", NULL, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:dns: + * + * List of DNS servers (network byte order). If the 'auto' method, these + * DNS servers are appended to those (if any) returned by automatic + * configuration. DNS servers cannot be used with the 'shared' or + * 'link-local' methods as there is no usptream network. In all other + * methods, these DNS servers are used as the only DNS servers for this + * connection. + **/ g_object_class_install_property (object_class, PROP_DNS, _nm_param_spec_specialized (NM_SETTING_IP4_CONFIG_DNS, "DNS", - "List of DNS servers", + "List of DNS servers (network byte order). If " + "the 'auto' method, these DNS servers are " + "appended to those (if any) returned by automatic " + "configuration. DNS servers cannot be used with " + "the 'shared' or 'link-local' methods as there is " + "no usptream network. In all other methods, " + "these DNS servers are used as the only DNS " + "servers for this connection.", DBUS_TYPE_G_UINT_ARRAY, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:dns-search: + * + * List of DNS search domains. If the 'auto' method is used, these search + * domains are appended to those returned by automatic configuration. + * Search domains cannot be used with the 'shared' or 'link-local' methods + * as there is no upstream network. In all other methods, these search + * domains are used as the only search domains for this connection. + **/ g_object_class_install_property (object_class, PROP_DNS_SEARCH, _nm_param_spec_specialized (NM_SETTING_IP4_CONFIG_DNS_SEARCH, "DNS search", - "List of DNS search domains", + "List of DNS search domains. If the 'auto' " + "method is used, these search domains are " + "appended to those returned by automatic " + "configuration. Search domains cannot be used " + "with the 'shared' or 'link-local' methods as " + "there is no upstream network. In all other " + "methods, these search domains are used as the " + "only search domains for this connection.", DBUS_TYPE_G_LIST_OF_STRING, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:addresses: + * + * Array of IPv4 address structures. Each IPv4 address structure is + * composed of 3 32-bit values; the first being the IPv4 address (network + * byte order), the second the prefix (1 - 32), and last the IPv4 gateway + * (network byte order). The gateway may be left as 0 if no gateway exists + * for that subnet. For the 'auto' method, given IP addresses are appended + * to those returned by automatic configuration. Addresses cannot be used + * with the 'shared' or 'link-local' methods as the interface is + * automatically assigned an address with these methods. + **/ g_object_class_install_property (object_class, PROP_ADDRESSES, _nm_param_spec_specialized (NM_SETTING_IP4_CONFIG_ADDRESSES, "Addresses", - "List of NMIP4Addresses", + "Array of IPv4 address structures. Each IPv4 " + "address structure is composed of 3 32-bit values; " + "the first being the IPv4 address (network byte " + "order), the second the prefix (1 - 32), and " + "last the IPv4 gateway (network byte order). The " + "gateway may be left as 0 if no gateway exists " + "for that subnet. For the 'auto' method, given " + "IP addresses are appended to those returned by " + "automatic configuration. Addresses cannot be " + "used with the 'shared' or 'link-local' methods " + "as the interface is automatically assigned an " + "address with these methods.", DBUS_TYPE_G_ARRAY_OF_ARRAY_OF_UINT, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:routes: + * + * Array of IPv4 route structures. Each IPv4 route structure is composed + * of 4 32-bit values; the first being the destination IPv4 network or + * address (network byte order), the second the destination network or + * address prefix (1 - 32), the third being the next-hop (network byte + * order) if any, and the fourth being the route metric. For the 'auto' + * method, given IP routes are appended to those returned by automatic + * configuration. Routes cannot be used with the 'shared' or 'link-local' + * methods because there is no upstream network. + **/ g_object_class_install_property (object_class, PROP_ROUTES, _nm_param_spec_specialized (NM_SETTING_IP4_CONFIG_ROUTES, "Routes", - "List of NMIP4Routes", + "Array of IPv4 route structures. Each IPv4 route " + "structure is composed of 4 32-bit values; the " + "first being the destination IPv4 network or " + "address (network byte order), the second the " + "destination network or address prefix (1 - 32), " + "the third being the next-hop (network byte order) " + "if any, and the fourth being the route metric. " + "For the 'auto' method, given IP routes are " + "appended to those returned by automatic " + "configuration. Routes cannot be used with the " + "'shared' or 'link-local' methods as there is no " + "upstream network.", DBUS_TYPE_G_ARRAY_OF_ARRAY_OF_UINT, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:ignore-auto-routes: + * + * When the method is set to 'auto' and this property to TRUE, automatically + * configured routes are ignored and only routes specified in + * #NMSettingIP4Config:routes, if any, are used. + **/ g_object_class_install_property (object_class, PROP_IGNORE_AUTO_ROUTES, g_param_spec_boolean (NM_SETTING_IP4_CONFIG_IGNORE_AUTO_ROUTES, "Ignore automatic routes", - "Ignore automatic routes", + "When the method is set to 'auto' and this property " + "to TRUE, automatically configured routes are " + "ignored and only routes specified in the 'routes' " + "property, if any, are used.", FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:ignore-auto-dns: + * + * When the method is set to 'auto' and this property to TRUE, automatically + * configured nameservers and search domains are ignored and only namservers + * and search domains specified in #NMSettingIP4Config:dns and + * #NMSettingIP4Config:dns-search, if any, are used. + **/ g_object_class_install_property (object_class, PROP_IGNORE_AUTO_DNS, g_param_spec_boolean (NM_SETTING_IP4_CONFIG_IGNORE_AUTO_DNS, "Ignore automatic DNS", - "Ignore automatic DNS", + "When the method is set to 'auto' and this property " + "to TRUE, automatically configured nameservers and " + "search domains are ignored and only namservers and " + "search domains specified in the 'dns' and 'dns-search' " + "properties, if any, are used.", FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:dhcp-client-id: + * + * A string sent to the DHCP server to identify the local machine which the + * DHCP server may use to cusomize the DHCP lease and options. + **/ g_object_class_install_property (object_class, PROP_DHCP_CLIENT_ID, g_param_spec_string (NM_SETTING_IP4_CONFIG_DHCP_CLIENT_ID, "DHCP Client ID", - "DHCP Client ID", + "A string sent to the DHCP server to identify the " + "local machine which the DHCP server may use to " + "cusomize the DHCP lease and options.", NULL, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:dhcp-send-hostname: + * + * If TRUE, a hostname is sent to the DHCP server when acquiring a lease. + * Some DHCP servers use this hostname to update DNS databases, essentially + * providing a static hostname for the computer. If + * #NMSettingIP4Config:dhcp-hostname is empty and this property is TRUE, + * the current persistent hostname of the computer is sent. + **/ g_object_class_install_property (object_class, PROP_DHCP_SEND_HOSTNAME, g_param_spec_boolean (NM_SETTING_IP4_CONFIG_DHCP_SEND_HOSTNAME, "Send DHCP hostname", - "Send the hostname to DHCP server", + "If TRUE, a hostname is sent to the DHCP server when " + "acquiring a lease. Some DHCP servers use this " + "hostname to update DNS databases, essentially " + "providing a static hostname for the computer. If " + "the 'dhcp-hostname' property is empty and this " + "property is TRUE, the current persistent hostname " + "of the computer is sent.", FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:dhcp-hostname: + * + * If the #NMSettingIP4Config:dhcp-send-hostname property is TRUE, then the + * specified name will be sent to the DHCP server when acquiring a lease. + **/ g_object_class_install_property (object_class, PROP_DHCP_HOSTNAME, g_param_spec_string (NM_SETTING_IP4_CONFIG_DHCP_HOSTNAME, "DHCP Hostname", - "DHCP Hostname", + "If the 'dhcp-send-hostname' property is TRUE, then " + "the specified name will be sent to the DHCP server " + "when acquiring a lease.", NULL, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingIP4Config:never-default: + * + * If TRUE, this connection will never be the default IPv4 connection, + * meaning it will never be assigned the default route by NetworkManager. + **/ g_object_class_install_property (object_class, PROP_NEVER_DEFAULT, g_param_spec_boolean (NM_SETTING_IP4_CONFIG_NEVER_DEFAULT, "Never default", - "Never make this connection the default IPv4 connection", + "If TRUE, this connection will never be the default " + "IPv4 connection, meaning it will never be assigned " + "the default route by NetworkManager.", FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE)); }