FreeBSD Manual Pages
COAP_PROXY(3) libcoap Manual COAP_PROXY(3) NAME coap_proxy, coap_proxy_forward_request, coap_proxy_forward_response, coap_verify_proxy_scheme_supported - Work with CoAP proxies SYNOPSIS #include <coap3/coap.h> int coap_proxy_forward_request(coap_session_t *session, const coap_pdu_t *request, coap_pdu_t *response, coap_resource_t *resource, coap_cache_key_t *cache_key, coap_proxy_server_list_t *server_list); coap_response_t coap_proxy_forward_response(coap_session_t *session, const coap_pdu_t *received_, coap_cache_key_t **cache_key); int coap_verify_proxy_scheme_supported(coap_uri_scheme_t scheme); For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls, -lcoap-3-wolfssl or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default (D)TLS library support. DESCRIPTION To simplify some of the CoAP proxy requirements, some of the proxy forward- ing functionality is provided by libcoap. The resourse handlers to handle forward or reverse proxy requests are de- fined using coap_resource_proxy_uri_init2(3) or coap_resource_re- verse_proxy_init*(3). FUNCTIONS Function: coap_proxy_forward_request() The coap_proxy_forward_request() function is called from a request handler when the request needs to be forwarded to an upstream server with a possi- ble change in protocol. Function: coap_proxy_forward_response() The coap_proxy_forward_response() function is used to cleanup / free any information set up by the coap_startup() function and should be the last coap_*() function called. The only safe function that can be called after coap_cleanup() is coap_startup() to re-initialize the libcoap logic. NOTE: Calling coap_cleanup() in one thread while continuing to use other coap_*() function calls in a different thread is not supported - even if they are using a different coap_context_t. NOTE: All other libcoap cleanups should called prior to coap_cleanup(), e.g. coap_free_context(3). Function: coap_verify_proxy_scheme_supported() The coap_proxy_forward_request() function is called from a request handler when the request needs to be forwarded to an upstream server with a possi- ble change in protocol. RETURN VALUES coap_proxy_forward_request() and coap_verify_proxy_scheme_supported() re- turn 1 on success and 0 on failure. coap_proxy_forward_response() returns one of COAP_RESPONSE_OK or COAP_RE- SPONSE_FAIL. EXAMPLES Forward Proxy Set Up #include <coap3/coap.h> static size_t proxy_host_name_count = 0; static const char **proxy_host_name_list = NULL; static coap_proxy_server_list_t forward_proxy = { NULL, 0, 0, COAP_PROXY_FORWARD, 0, 300}; static void hnd_forward_proxy_uri(coap_resource_t *resource, coap_session_t *session, const coap_pdu_t *request, const coap_string_t *query COAP_UNUSED, coap_pdu_t *response) { if (!coap_proxy_forward_request(session, request, response, resource, NULL, &forward_proxy)) { coap_log_debug("hnd_forward_proxy_uri: Failed to forward PDU\n"); /* Non ACK response code set on error detection */ } /* Leave response code as is */ } static coap_response_t proxy_response_handler(coap_session_t *session, const coap_pdu_t *sent COAP_UNUSED, const coap_pdu_t *received, const coap_mid_t id COAP_UNUSED) { return coap_proxy_forward_response(session, received, NULL); } static void init_resources(coap_context_t *ctx) { coap_resource_t *r; /* See coap_resource_proxy_uri_init2(3) */ r = coap_resource_proxy_uri_init2(hnd_forward_proxy_uri, proxy_host_name_count, proxy_host_name_list, 0); coap_add_resource(ctx, r); coap_register_response_handler(ctx, proxy_response_handler); /* Add in event or nack handlers if required */ } static void init_proxy_info(coap_uri_t *proxy_uri, const char *proxy_host_name) { coap_proxy_server_t *new_entry; new_entry = realloc(forward_proxy.entry, (forward_proxy.entry_count + 1)*sizeof(forward_proxy.entry[0])); if (!new_entry) { coap_log_err("CoAP Proxy realloc() error\n"); return; } /* Can have multiple of these upstream proxy hosts for doing round robin etc. */ forward_proxy.entry = new_entry; memset(&forward_proxy.entry[forward_proxy.entry_count], 0, sizeof(forward_proxy.entry[0])); forward_proxy.entry[forward_proxy.entry_count].uri = *proxy_uri; forward_proxy.entry_count++; /* The proxy host could be known by multile names - add them all in */ proxy_host_name_count = 0; proxy_host_name_list = coap_malloc(proxy_host_name_count * sizeof(char *)); proxy_host_name_list[0] = proxy_host_name; } Reverse Proxy Set Up #include <coap3/coap.h> static coap_proxy_server_list_t reverse_proxy = { NULL, 0, 0, COAP_PROXY_REVERSE_STRIP, 0, 10}; static void hnd_reverse_proxy_uri(coap_resource_t *resource, coap_session_t *session, const coap_pdu_t *request, const coap_string_t *query COAP_UNUSED, coap_pdu_t *response) { if (!coap_proxy_forward_request(session, request, response, resource, NULL, &reverse_proxy)) { coap_log_debug("hnd_reverse_proxy: Failed to forward PDU\n"); /* Non ACK response code set on error detection */ } /* Leave response code as is */ } static coap_response_t proxy_response_handler(coap_session_t *session, const coap_pdu_t *sent COAP_UNUSED, const coap_pdu_t *received, const coap_mid_t id COAP_UNUSED) { return coap_proxy_forward_response(session, received, NULL); } static void init_resources(coap_context_t *ctx) { coap_resource_t *r; /* See coap_resource_reverse_proxy_init(3) */ r = coap_resource_reverse_proxy_init(hnd_reverse_proxy_uri, 0); coap_add_resource(ctx, r); coap_register_response_handler(ctx, proxy_response_handler); /* Add in event or nack handlers if required */ } FURTHER INFORMATION See "RFC7252: The Constrained Application Protocol (CoAP)" for further information. BUGS Please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs. Please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. AUTHORS The libcoap project <libcoap-developers@lists.sourceforge.net> coap_proxy 4.3.5 08/02/2026 COAP_PROXY(3)
NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | RETURN VALUES | EXAMPLES | FURTHER INFORMATION | BUGS | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=coap_proxy&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>