1 /* 2 * Copyright (c) 2016-2017, Marie Helene Kvello-Aune 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without modification, 6 * are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, 9 * thislist of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright notice, 12 * this list of conditions and the following disclaimer in the documentation and/or 13 * other materials provided with the distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 16 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 17 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 22 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 */ 26 27 #pragma once 28 29 #include <sys/types.h> 30 31 #include <net/if.h> 32 33 #include <netinet/in.h> 34 #include <netinet/ip_carp.h> 35 #include <netinet6/in6_var.h> 36 37 #define ND6_IFF_DEFAULTIF 0x8000 38 39 typedef enum { 40 OK = 0, 41 OTHER, 42 IOCTL, 43 SOCKET, 44 NETLINK 45 } ifconfig_errtype; 46 47 /* 48 * Opaque definition so calling application can just pass a 49 * pointer to it for library use. 50 */ 51 struct ifconfig_handle; 52 typedef struct ifconfig_handle ifconfig_handle_t; 53 54 struct ifaddrs; 55 struct ifbropreq; 56 struct ifbreq; 57 struct in6_ndireq; 58 struct lagg_reqall; 59 struct lagg_reqflags; 60 struct lagg_reqopts; 61 struct lagg_reqport; 62 63 /** Stores extra info associated with a bridge(4) interface */ 64 struct ifconfig_bridge_status { 65 struct ifbropreq *params; /**< current operational parameters */ 66 struct ifbreq *members; /**< list of bridge members */ 67 size_t members_count; /**< how many member interfaces */ 68 uint32_t cache_size; /**< size of address cache */ 69 uint32_t cache_lifetime; /**< address cache entry lifetime */ 70 }; 71 72 struct ifconfig_capabilities { 73 /** Current capabilities (ifconfig prints this as 'options')*/ 74 int curcap; 75 /** Requested capabilities (ifconfig prints this as 'capabilities')*/ 76 int reqcap; 77 }; 78 79 /** Stores extra info associated with an inet address */ 80 struct ifconfig_inet_addr { 81 const struct sockaddr_in *sin; 82 const struct sockaddr_in *netmask; 83 const struct sockaddr_in *dst; 84 const struct sockaddr_in *broadcast; 85 int prefixlen; 86 uint8_t vhid; 87 }; 88 89 /** Stores extra info associated with an inet6 address */ 90 struct ifconfig_inet6_addr { 91 struct sockaddr_in6 *sin6; 92 struct sockaddr_in6 *dstin6; 93 struct in6_addrlifetime lifetime; 94 int prefixlen; 95 uint32_t flags; 96 uint8_t vhid; 97 }; 98 99 /** Stores extra info associated with a lagg(4) interface */ 100 struct ifconfig_lagg_status { 101 struct lagg_reqall *ra; 102 struct lagg_reqopts *ro; 103 struct lagg_reqflags *rf; 104 }; 105 106 /** Retrieves a new state object for use in other API calls. 107 * Example usage: 108 *{@code 109 * // Create state object 110 * ifconfig_handle_t *lifh; 111 * lifh = ifconfig_open(); 112 * if (lifh == NULL) { 113 * // Handle error 114 * } 115 * 116 * // Do stuff with the handle 117 * 118 * // Dispose of the state object 119 * ifconfig_close(lifh); 120 * lifh = NULL; 121 *} 122 */ 123 ifconfig_handle_t *ifconfig_open(void); 124 125 /** Frees resources held in the provided state object. 126 * @param h The state object to close. 127 * @see #ifconfig_open(void) 128 */ 129 void ifconfig_close(ifconfig_handle_t *h); 130 131 /** Identifies what kind of error occurred. */ 132 ifconfig_errtype ifconfig_err_errtype(ifconfig_handle_t *h); 133 134 /** Retrieves the errno associated with the error, if any. */ 135 int ifconfig_err_errno(ifconfig_handle_t *h); 136 137 typedef void (*ifconfig_foreach_func_t)(ifconfig_handle_t *h, 138 struct ifaddrs *ifa, void *udata); 139 140 /** Iterate over every network interface 141 * @param h An open ifconfig state object 142 * @param cb A callback function to call with a pointer to each interface 143 * @param udata An opaque value that will be passed to the callback. 144 * @return 0 on success, nonzero if the list could not be iterated 145 */ 146 int ifconfig_foreach_iface(ifconfig_handle_t *h, ifconfig_foreach_func_t cb, 147 void *udata); 148 149 /** Iterate over every address on a single network interface 150 * @param h An open ifconfig state object 151 * @param ifa A pointer that was supplied by a previous call to 152 * ifconfig_foreach_iface 153 * @param udata An opaque value that will be passed to the callback. 154 * @param cb A callback function to call with a pointer to each ifaddr 155 */ 156 void ifconfig_foreach_ifaddr(ifconfig_handle_t *h, struct ifaddrs *ifa, 157 ifconfig_foreach_func_t cb, void *udata); 158 159 /** If error type was IOCTL, this identifies which request failed. */ 160 unsigned long ifconfig_err_ioctlreq(ifconfig_handle_t *h); 161 int ifconfig_get_description(ifconfig_handle_t *h, const char *name, 162 char **description); 163 int ifconfig_set_description(ifconfig_handle_t *h, const char *name, 164 const char *newdescription); 165 int ifconfig_unset_description(ifconfig_handle_t *h, const char *name); 166 int ifconfig_set_name(ifconfig_handle_t *h, const char *name, 167 const char *newname); 168 int ifconfig_get_orig_name(ifconfig_handle_t *h, const char *ifname, 169 char **orig_name); 170 int ifconfig_set_fib(ifconfig_handle_t *h, const char *name, int fib); 171 int ifconfig_get_fib(ifconfig_handle_t *h, const char *name, int *fib); 172 int ifconfig_set_mtu(ifconfig_handle_t *h, const char *name, const int mtu); 173 int ifconfig_get_mtu(ifconfig_handle_t *h, const char *name, int *mtu); 174 int ifconfig_get_nd6(ifconfig_handle_t *h, const char *name, 175 struct in6_ndireq *nd); 176 int ifconfig_set_metric(ifconfig_handle_t *h, const char *name, 177 const int metric); 178 int ifconfig_get_metric(ifconfig_handle_t *h, const char *name, int *metric); 179 int ifconfig_set_capability(ifconfig_handle_t *h, const char *name, 180 const int capability); 181 int ifconfig_get_capability(ifconfig_handle_t *h, const char *name, 182 struct ifconfig_capabilities *capability); 183 184 /** Retrieve the list of groups to which this interface belongs 185 * @param h An open ifconfig state object 186 * @param name The interface name 187 * @param ifgr return argument. The caller is responsible for freeing 188 * ifgr->ifgr_groups 189 * @return 0 on success, nonzero on failure 190 */ 191 int ifconfig_get_groups(ifconfig_handle_t *h, const char *name, 192 struct ifgroupreq *ifgr); 193 int ifconfig_get_ifstatus(ifconfig_handle_t *h, const char *name, 194 struct ifstat *stat); 195 196 /** Retrieve the interface media information 197 * @param h An open ifconfig state object 198 * @param name The interface name 199 * @param ifmr Return argument. The caller is responsible for freeing it 200 * @return 0 on success, nonzero on failure 201 */ 202 int ifconfig_media_get_mediareq(ifconfig_handle_t *h, const char *name, 203 struct ifmediareq **ifmr); 204 205 const char *ifconfig_media_get_status(const struct ifmediareq *ifmr); 206 207 typedef int ifmedia_t; 208 209 #define INVALID_IFMEDIA ((ifmedia_t)-1) 210 211 /** Retrieve the name of a media type 212 * @param media The media to be named 213 * @return A pointer to the media type name, or NULL on failure 214 */ 215 const char *ifconfig_media_get_type(ifmedia_t media); 216 217 /** Retrieve a media type by its name 218 * @param name The name of a media type 219 * @return The media type value, or INVALID_IFMEDIA on failure 220 */ 221 ifmedia_t ifconfig_media_lookup_type(const char *name); 222 223 /** Retrieve the name of a media subtype 224 * @param media The media subtype to be named 225 * @return A pointer to the media subtype name, or NULL on failure 226 */ 227 const char *ifconfig_media_get_subtype(ifmedia_t media); 228 229 /** Retrieve a media subtype by its name 230 * @param media The top level media type whose subtype we want 231 * @param name The name of a media subtype 232 * @return The media subtype value, or INVALID_IFMEDIA on failure 233 */ 234 ifmedia_t ifconfig_media_lookup_subtype(ifmedia_t media, const char *name); 235 236 /** Retrieve the name of a media mode 237 * @param media The media mode to be named 238 * @return A pointer to the media mode name, or NULL on failure 239 */ 240 const char *ifconfig_media_get_mode(ifmedia_t media); 241 242 /** Retrieve a media mode by its name 243 * @param media The top level media type whose mode we want 244 * @param name The name of a media mode 245 * @return The media mode value, or INVALID_IFMEDIA on failure 246 */ 247 ifmedia_t ifconfig_media_lookup_mode(ifmedia_t media, const char *name); 248 249 /** Retrieve an array of media options 250 * @param media The media for which to obtain the options 251 * @return Pointer to an array of pointers to option names, 252 * terminated by a NULL pointer, or simply NULL on failure. 253 * The caller is responsible for freeing the array but not its 254 * contents. 255 */ 256 const char **ifconfig_media_get_options(ifmedia_t media); 257 258 /** Retrieve an array of media options by names 259 * @param media The top level media type whose options we want 260 * @param opts Pointer to an array of string pointers naming options 261 * @param nopts Number of elements in the opts array 262 * @return Pointer to an array of media options, one for each option named 263 * in opts. NULL is returned instead with errno set to ENOMEM if 264 * allocating the return array fails or EINVAL if media is not 265 * valid. A media option in the array will be INVALID_IFMEDIA 266 * when lookup failed for the option named in that position in 267 * opts. The caller is responsible for freeing the array. 268 */ 269 ifmedia_t *ifconfig_media_lookup_options(ifmedia_t media, const char **opts, 270 size_t nopts); 271 272 /** Retrieve the reason the interface is down 273 * @param h An open ifconfig state object 274 * @param name The interface name 275 * @param ifdr Return argument. 276 * @return 0 on success, nonzero on failure 277 */ 278 int ifconfig_media_get_downreason(ifconfig_handle_t *h, const char *name, 279 struct ifdownreason *ifdr); 280 281 struct ifconfig_carp { 282 size_t carpr_count; 283 uint32_t carpr_vhid; 284 uint32_t carpr_state; 285 int32_t carpr_advbase; 286 int32_t carpr_advskew; 287 uint8_t carpr_key[CARP_KEY_LEN]; 288 struct in_addr carpr_addr; 289 struct in6_addr carpr_addr6; 290 }; 291 292 int ifconfig_carp_get_vhid(ifconfig_handle_t *h, const char *name, 293 struct ifconfig_carp *carpr, uint32_t vhid); 294 int ifconfig_carp_get_info(ifconfig_handle_t *h, const char *name, 295 struct ifconfig_carp *carpr, size_t ncarp); 296 int ifconfig_carp_set_info(ifconfig_handle_t *h, const char *name, 297 const struct ifconfig_carp *carpr); 298 299 /** Retrieve additional information about an inet address 300 * @param h An open ifconfig state object 301 * @param name The interface name 302 * @param ifa Pointer to the address structure of interest 303 * @param addr Return argument. It will be filled with additional information 304 * about the address. 305 * @return 0 on success, nonzero on failure. 306 */ 307 int ifconfig_inet_get_addrinfo(ifconfig_handle_t *h, 308 const char *name, struct ifaddrs *ifa, struct ifconfig_inet_addr *addr); 309 310 /** Retrieve additional information about an inet6 address 311 * @param h An open ifconfig state object 312 * @param name The interface name 313 * @param ifa Pointer to the address structure of interest 314 * @param addr Return argument. It will be filled with additional information 315 * about the address. 316 * @return 0 on success, nonzero on failure. 317 */ 318 int ifconfig_inet6_get_addrinfo(ifconfig_handle_t *h, 319 const char *name, struct ifaddrs *ifa, struct ifconfig_inet6_addr *addr); 320 321 /** Retrieve additional information about a bridge(4) interface */ 322 int ifconfig_bridge_get_bridge_status(ifconfig_handle_t *h, 323 const char *name, struct ifconfig_bridge_status **bridge); 324 325 /** Frees the structure returned by ifconfig_bridge_get_bridge_status. Does 326 * nothing if the argument is NULL 327 * @param bridge Pointer to the structure to free 328 */ 329 void ifconfig_bridge_free_bridge_status(struct ifconfig_bridge_status *bridge); 330 331 /** Retrieve additional information about a lagg(4) interface */ 332 int ifconfig_lagg_get_lagg_status(ifconfig_handle_t *h, 333 const char *name, struct ifconfig_lagg_status **lagg_status); 334 335 /** Retrieve additional information about a member of a lagg(4) interface */ 336 int ifconfig_lagg_get_laggport_status(ifconfig_handle_t *h, 337 const char *name, struct lagg_reqport *rp); 338 339 /** Frees the structure returned by ifconfig_lagg_get_lagg_status. Does 340 * nothing if the argument is NULL 341 * @param laggstat Pointer to the structure to free 342 */ 343 void ifconfig_lagg_free_lagg_status(struct ifconfig_lagg_status *laggstat); 344 345 /** Destroy a virtual interface 346 * @param name Interface to destroy 347 */ 348 int ifconfig_destroy_interface(ifconfig_handle_t *h, const char *name); 349 350 /** Creates a (virtual) interface 351 * @param name Name of interface to create. Example: bridge or bridge42 352 * @param name ifname Is set to actual name of created interface 353 */ 354 int ifconfig_create_interface(ifconfig_handle_t *h, const char *name, 355 char **ifname); 356 357 /** Creates a (virtual) interface 358 * @param name Name of interface to create. Example: vlan0 or ix0.50 359 * @param name ifname Is set to actual name of created interface 360 * @param vlandev Name of interface to attach to 361 * @param vlanid VLAN ID/Tag. Must not be 0. 362 */ 363 int ifconfig_create_interface_vlan(ifconfig_handle_t *h, const char *name, 364 char **ifname, const char *vlandev, const unsigned short vlantag); 365 366 int ifconfig_set_vlantag(ifconfig_handle_t *h, const char *name, 367 const char *vlandev, const unsigned short vlantag); 368 369 /** Gets the names of all interface cloners available on the system 370 * @param bufp Set to the address of the names buffer on success or NULL 371 * if an error occurs. This buffer must be freed when done. 372 * @param lenp Set to the number of names in the returned buffer or 0 373 * if an error occurs. Each name is contained within an 374 * IFNAMSIZ length slice of the buffer, for a total buffer 375 * length of *lenp * IFNAMSIZ bytes. 376 */ 377 int ifconfig_list_cloners(ifconfig_handle_t *h, char **bufp, size_t *lenp); 378