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