log/sinks/syslog_backend.hpp

0001 /*
0002  *          Copyright Andrey Semashev 2007 - 2015.
0003  * Distributed under the Boost Software License, Version 1.0.
0004  *    (See accompanying file LICENSE_1_0.txt or copy at
0005  *          http://www.boost.org/LICENSE_1_0.txt)
0006  */
0007 /*!
0008  * \file   syslog_backend.hpp
0009  * \author Andrey Semashev
0010  * \date   08.01.2008
0011  *
0012  * The header contains implementation of a Syslog sink backend along with its setup facilities.
0013  */
0014
0015 #ifndef BOOST_LOG_SINKS_SYSLOG_BACKEND_HPP_INCLUDED_
0016 #define BOOST_LOG_SINKS_SYSLOG_BACKEND_HPP_INCLUDED_
0017
0018 #include <boost/log/detail/config.hpp>
0019
0020 #ifdef BOOST_HAS_PRAGMA_ONCE
0021 #pragma once
0022 #endif
0023
0024 #ifndef BOOST_LOG_WITHOUT_SYSLOG
0025
0026 #include <string>
0027 #include <boost/log/detail/asio_fwd.hpp>
0028 #include <boost/log/detail/light_function.hpp>
0029 #include <boost/log/detail/parameter_tools.hpp>
0030 #include <boost/log/sinks/basic_sink_backend.hpp>
0031 #include <boost/log/sinks/syslog_constants.hpp>
0032 #include <boost/log/sinks/attribute_mapping.hpp>
0033 #include <boost/log/attributes/attribute_value_set.hpp>
0034 #include <boost/log/keywords/facility.hpp>
0035 #include <boost/log/keywords/use_impl.hpp>
0036 #include <boost/log/keywords/ident.hpp>
0037 #include <boost/log/keywords/ip_version.hpp>
0038 #include <boost/log/detail/header.hpp>
0039
0040 namespace boost {
0041
0042 BOOST_LOG_OPEN_NAMESPACE
0043
0044 namespace sinks {
0045
0046 //! Supported IP protocol versions
0047 enum ip_versions
0048 {
0049     v4,
0050     v6
0051 };
0052
0053 namespace syslog {
0054
0055     //! The enumeration defined the possible implementation types for the syslog backend
0056     enum impl_types
0057     {
0058 #ifdef BOOST_LOG_USE_NATIVE_SYSLOG
0059         native = 0                  //!< Use native syslog API
0060 #ifndef BOOST_LOG_NO_ASIO
0061         ,
0062 #endif
0063 #endif
0064 #ifndef BOOST_LOG_NO_ASIO
0065         udp_socket_based = 1        //!< Use UDP sockets, according to RFC3164
0066 #endif
0067     };
0068
0069     /*!
0070      * \brief Straightforward severity level mapping
0071      *
0072      * This type of mapping assumes that attribute with a particular name always
0073      * provides values that map directly onto the Syslog levels. The mapping
0074      * simply returns the extracted attribute value converted to the Syslog severity level.
0075      */
0076     template< typename AttributeValueT = int >
0077     class direct_severity_mapping :
0078         public basic_direct_mapping< level, AttributeValueT >
0079     {
0080         //! Base type
0081         typedef basic_direct_mapping< level, AttributeValueT > base_type;
0082
0083     public:
0084         /*!
0085          * Constructor
0086          *
0087          * \param name Attribute name
0088          */
0089         explicit direct_severity_mapping(attribute_name const& name) :
0090             base_type(name, info)
0091         {
0092         }
0093     };
0094
0095     /*!
0096      * \brief Customizable severity level mapping
0097      *
0098      * The class allows to setup a custom mapping between an attribute and Syslog severity levels.
0099      * The mapping should be initialized similarly to the standard \c map container, by using
0100      * indexing operator and assignment.
0101      */
0102     template< typename AttributeValueT = int >
0103     class custom_severity_mapping :
0104         public basic_custom_mapping< level, AttributeValueT >
0105     {
0106         //! Base type
0107         typedef basic_custom_mapping< level, AttributeValueT > base_type;
0108
0109     public:
0110         /*!
0111          * Constructor
0112          *
0113          * \param name Attribute name
0114          */
0115         explicit custom_severity_mapping(attribute_name const& name) :
0116             base_type(name, info)
0117         {
0118         }
0119     };
0120
0121 } // namespace syslog
0122
0123 /*!
0124  * \brief An implementation of a syslog sink backend
0125  *
0126  * The backend provides support for the syslog protocol, defined in RFC3164.
0127  * The backend sends log records to a remote host via UDP. The host name can
0128  * be specified by calling the \c set_target_address method. By default log
0129  * records will be sent to localhost:514. The local address can be specified
0130  * as well, by calling the \c set_local_address method. By default syslog
0131  * packets will be sent from any local address available.
0132  *
0133  * It is safe to create several sink backends with the same local addresses -
0134  * the backends within the process will share the same socket. The same applies
0135  * to different processes that use the syslog backends to send records from
0136  * the same socket. However, it is not guaranteed to work if some third party
0137  * facility is using the socket.
0138  *
0139  * On systems with native syslog implementation it may be preferable to utilize
0140  * the POSIX syslog API instead of direct socket management in order to bypass
0141  * possible security limitations that may be in action. To do so one has to pass
0142  * the <tt>use_impl = native</tt> to the backend constructor. Note, however,
0143  * that in that case you will only have one chance to specify syslog facility and
0144  * process identification string - on the first native syslog backend construction.
0145  * Other native syslog backends will ignore these parameters.
0146  * Obviously, the \c set_local_address and \c set_target_address
0147  * methods have no effect for native backends. Using <tt>use_impl = native</tt>
0148  * on platforms with no native support for POSIX syslog API will have no effect.
0149  */
0150 class syslog_backend :
0151     public basic_formatted_sink_backend< char >
0152 {
0153     //! Base type
0154     typedef basic_formatted_sink_backend< char > base_type;
0155     //! Implementation type
0156     struct implementation;
0157
0158 public:
0159     //! Character type
0160     typedef base_type::char_type char_type;
0161     //! String type that is used to pass message test
0162     typedef base_type::string_type string_type;
0163
0164     //! Syslog severity level mapper type
0165     typedef boost::log::aux::light_function< syslog::level (record_view const&) > severity_mapper_type;
0166
0167 private:
0168     //! Pointer to the implementation
0169     implementation* m_pImpl;
0170
0171 public:
0172     /*!
0173      * Constructor. Creates a UDP socket-based backend with <tt>syslog::user</tt> facility code.
0174      * IPv4 protocol will be used.
0175      */
0176     BOOST_LOG_API syslog_backend();
0177     /*!
0178      * Constructor. Creates a sink backend with the specified named parameters.
0179      * The following named parameters are supported:
0180      *
0181      * \li \c facility - Specifies the facility code. If not specified, <tt>syslog::user</tt> will be used.
0182      * \li \c use_impl - Specifies the backend implementation. Can be one of:
0183      *                   \li \c native - Use the native syslog API, if available. If no native API
0184      *                                   is available, it is equivalent to \c udp_socket_based.
0185      *                   \li \c udp_socket_based - Use the UDP socket-based implementation, conforming to
0186      *                                             RFC3164 protocol specification. This is the default.
0187      * \li \c ip_version - Specifies IP protocol version to use, in case if socket-based implementation
0188      *                     is used. Can be either \c v4 (the default one) or \c v6.
0189      * \li \c ident - Process identification string. This parameter is only supported by native syslog implementation.
0190      */
0191 #ifndef BOOST_LOG_DOXYGEN_PASS
0192     BOOST_LOG_PARAMETRIZED_CONSTRUCTORS_CALL(syslog_backend, construct)
0193 #else
0194     template< typename... ArgsT >
0195     explicit syslog_backend(ArgsT... const& args);
0196 #endif
0197
0198     /*!
0199      * Destructor
0200      */
0201     BOOST_LOG_API ~syslog_backend();
0202
0203     /*!
0204      * The method installs the function object that maps application severity levels to syslog levels
0205      */
0206     BOOST_LOG_API void set_severity_mapper(severity_mapper_type const& mapper);
0207
0208 #if !defined(BOOST_LOG_NO_ASIO)
0209
0210     /*!
0211      * The method sets the local host name which log records will be sent from. The host name
0212      * is resolved to obtain the final IP address.
0213      *
0214      * \note Does not have effect if the backend was constructed to use native syslog API
0215      *
0216      * \param addr The local address
0217      * \param port The local port number
0218      */
0219     BOOST_LOG_API void set_local_address(std::string const& addr, unsigned short port = 514);
0220     /*!
0221      * The method sets the local address which log records will be sent from.
0222      *
0223      * \note Does not have effect if the backend was constructed to use native syslog API
0224      *
0225      * \param addr The local address
0226      * \param port The local port number
0227      */
0228     BOOST_LOG_API void set_local_address(boost::asio::ip::address const& addr, unsigned short port = 514);
0229
0230     /*!
0231      * The method sets the remote host name where log records will be sent to. The host name
0232      * is resolved to obtain the final IP address.
0233      *
0234      * \note Does not have effect if the backend was constructed to use native syslog API
0235      *
0236      * \param addr The remote host address
0237      * \param port The port number on the remote host
0238      */
0239     BOOST_LOG_API void set_target_address(std::string const& addr, unsigned short port = 514);
0240     /*!
0241      * The method sets the address of the remote host where log records will be sent to.
0242      *
0243      * \note Does not have effect if the backend was constructed to use native syslog API
0244      *
0245      * \param addr The remote host address
0246      * \param port The port number on the remote host
0247      */
0248     BOOST_LOG_API void set_target_address(boost::asio::ip::address const& addr, unsigned short port = 514);
0249
0250 #endif // !defined(BOOST_LOG_NO_ASIO)
0251
0252     /*!
0253      * The method passes the formatted message to the syslog API or sends to a syslog server
0254      */
0255     BOOST_LOG_API void consume(record_view const& rec, string_type const& formatted_message);
0256
0257 private:
0258 #ifndef BOOST_LOG_DOXYGEN_PASS
0259     //! The method creates the backend implementation
0260     template< typename ArgsT >
0261     void construct(ArgsT const& args)
0262     {
0263         construct(
0264             args[keywords::facility | syslog::user],
0265 #if !defined(BOOST_LOG_NO_ASIO)
0266             args[keywords::use_impl | syslog::udp_socket_based],
0267 #else
0268             args[keywords::use_impl | syslog::native],
0269 #endif
0270             args[keywords::ip_version | v4],
0271             args[keywords::ident | std::string()]);
0272     }
0273     BOOST_LOG_API void construct(
0274         syslog::facility facility, syslog::impl_types use_impl, ip_versions ip_version, std::string const& ident);
0275 #endif // BOOST_LOG_DOXYGEN_PASS
0276 };
0277
0278 } // namespace sinks
0279
0280 BOOST_LOG_CLOSE_NAMESPACE // namespace log
0281
0282 } // namespace boost
0283
0284 #include <boost/log/detail/footer.hpp>
0285
0286 #endif // BOOST_LOG_WITHOUT_SYSLOG
0287
0288 #endif // BOOST_LOG_SINKS_SYSLOG_BACKEND_HPP_INCLUDED_