diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 313 |
1 files changed, 111 insertions, 202 deletions
@@ -1,202 +1,111 @@ -# puppet-rsyslog [](https://travis-ci.org/saz/puppet-rsyslog)
-
-Manage rsyslog client and server via Puppet
-
-## REQUIREMENTS
-
-* Puppet >=2.6 if using parameterized classes
-* Currently supports Ubuntu >=11.04 & Debian running rsyslog >=4.5
-
-## USAGE
-
-### Client
-
-#### Using default values
-```
- class { 'rsyslog::client': }
-```
-
-#### Variables and default values
-```
- class { 'rsyslog::client':
- log_remote => true,
- spool_size => '1g',
- remote_type => 'tcp',
- remote_forward_format => 'RSYSLOG_ForwardFormat',
- log_local => false,
- log_auth_local => false,
- custom_config => undef,
- custom_params => undef,
- server => 'log',
- port => '514',
- remote_servers => false,
- ssl_ca => undef,
- log_templates => false,
- actionfiletemplate => false
- }
-```
-for read from file
-```
- rsyslog::imfile { 'my-imfile':
- file_name => '/some/file',
- file_tag => 'mytag',
- file_facility => 'myfacility',
- }
-
-```
-
-#### Defining custom logging templates
-
-The `log_templates` parameter can be used to set up custom logging templates, which can be used for local and/or remote logging. More detail on template formats can be found in the [rsyslog documentation](http://www.rsyslog.com/doc/rsyslog_conf_templates.html).
-
-The following examples sets up a custom logging template as per [RFC3164fmt](https://www.ietf.org/rfc/rfc3164.txt):
-
-```puppet
-class{'rsyslog::client':
- log_templates => [
- {
- name => 'RFC3164fmt',
- template => '<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%',
- },
- ]
-}
-```
-
-#### Logging to multiple remote servers
-
-The `remote_servers` parameter can be used to set up logging to multiple remote servers which are supplied as a list of key value pairs for each remote. There is an example configuration provided in `./test/multiple_hosts.pp`
-
-Using the `remote_servers` parameter over-rides the other remote sever parameters, and they will not be used in the client configuration file:
-* `log_remote`
-* `remote_type`
-* `server`
-* `port`
-
-The following example sets up three remote logging hosts for the client:
-
-```puppet
-class{'rsyslog::client':
- remote_servers => [
- {
- host => 'logs.example.org',
- },
- {
- port => '55514',
- },
- {
- host => 'logs.somewhere.com',
- port => '555',
- pattern => '*.log',
- protocol => 'tcp',
- format => 'RFC3164fmt',
- },
- ]
-}
-```
-
-Each host has the following parameters:
-* *host*: Sets the address or hostname of the remote logging server. Defaults to `localhost`
-* *port*: Sets the port the host is listening on. Defaults to `514`
-* *pattern*: Sets the pattern to match logs. Defaults to `*.*`
-* *protocol*: Sets the protocol. Only recognises TCP and UDP. Defaults to UDP
-* *format*: Sets the log format. Defaults to not specifying log format, which defaults to the format set by `ActionFileDefaultTemplate` in the client configuration.
-
-#### Logging to a MySQL or PostgreSQL database
-
-Events can also be logged to a MySQL or PostgreSQL database. The database needs to be deployed separately, either locally or remotely. Schema are available from the `rsyslog` source:
-
- * [MySQL schema](http://git.adiscon.com/?p=rsyslog.git;a=blob_plain;f=plugins/ommysql/createDB.sql)
- * [PostgreSQL schema](http://git.adiscon.com/?p=rsyslog.git;a=blob_plain;f=plugins/ompgsql/createDB.sql)
-
-Declare the following to configure the connection:
-````
- class { 'rsyslog::database':
- backend => 'mysql',
- server => 'localhost',
- database => 'Syslog',
- username => 'rsyslog',
- password => 'secret',
- }
-````
-### Server
-
-#### Using default values
-```
- class { 'rsyslog::server': }
-```
-
-#### Variables and default values
-```
- class { 'rsyslog::server':
- enable_tcp => true,
- enable_udp => true,
- enable_onefile => false,
- server_dir => '/srv/log/',
- custom_config => undef,
- high_precision_timestamps => false,
- }
-```
-
-Both can be installed at the same time.
-
-## PARAMETERS
-
-The following lists all the class parameters this module accepts.
-
- RSYSLOG::SERVER CLASS PARAMETERS VALUES DESCRIPTION
- -------------------------------------------------------------------
- enable_tcp true,false Enable TCP listener. Defaults to true.
- enable_udp true,false Enable UDP listener. Defaults to true.
- enable_onefile true,false Only one logfile per remote host. Defaults to false.
- server_dir STRING Folder where logs will be stored on the server. Defaults to '/srv/log/'
- custom_config STRING Specify your own template to use for server config. Defaults to undef. Example usage: custom_config => 'rsyslog/my_config.erb'
- high_precision_timestamps true,false Whether or not to use high precision timestamps.
- remote_servers HASH Provides a hash of multiple remote logging servers. Check documentation.
-
- RSYSLOG::CLIENT CLASS PARAMETERS VALUES DESCRIPTION
- -------------------------------------------------------------------
- log_remote true,false Log Remotely. Defaults to true.
- spool_size STRING Max size for disk queue if remote server failed. Defaults to '1g'.
- remote_type 'tcp','udp' Which protocol to use when logging remotely. Defaults to 'tcp'.
- remote_forward_format STRING Which forward format for remote servers should be used. Only used if remote_servers is false.
- log_local true,false Log locally. Defaults to false.
- log_auth_local true,false Just log auth facility locally. Defaults to false.
- custom_config STRING Specify your own template to use for client config. Defaults to undef. Example usage: custom_config => 'rsyslog/my_config.erb'
- custom_params TODO TODO
- server STRING Rsyslog server to log to. Will be used in the client configuration file. Only used, if remote_servers is false.
- port '514' Remote server port. Only used if remote_servers is false.
- remote_servers Array of hashes Array of hashes with remote servers. See documentation above. Defaults to false.
- ssl_ca STRING SSL CA file location. Defaults to undef.
- log_templates HASH Provides a has defining custom logging templates using the `$template` configuration parameter.
- actionfiletemplate STRING If set this defines the `ActionFileDefaultTemplate` which sets the default logging format for remote and local logging.
-
- RSYSLOG::DATABASE CLASS PARAMETERS VALUES DESCRIPTION
- -------------------------------------------------------------------
- backend 'mysql','pgsql' Database backend (MySQL or PostgreSQL).
- server STRING Database server.
- database STRING Database name.
- username STRING Database username.
- password STRING Database password.
-
-### Other notes
-
-Due to a missing feature in current RELP versions (InputRELPServerBindRuleset option),
-remote logging is using TCP. You can switch between TCP and UDP. As soon as there is
-a new RELP version which supports setting Rulesets, I will add support for relp back.
-
-By default, rsyslog::server will strip numbers from hostnames. This means the logs of
-multiple servers with the same non-numerical name will be aggregrated in a single
-directory. i.e. www01 www02 and www02 would all log to the www directory.
-
-To log each host to a seperate directory, set the custom_config parameter to
-'rsyslog/server-hostname.conf.erb'
-
-If any of the following parameters are set to `false`, then the module will not
-manage the respective package:
-
- gnutls_package_name
- relp_package_name
- rsyslog_package_name
-
-This can be used when using the adiscon PPA repository, that has merged rsyslog-gnutls
-with the main rsyslog package.
+Leap Platform +============================= + +[](https://jenkins.leap.se/job/platform_develop/) + +The LEAP Platform is set of complementary packages and server recipes to automate the maintenance of LEAP services in a hardened Debian environment. Its goal is to make it as painless as possible for sysadmins to deploy and maintain a service provider's infrastructure for secure communication. These recipes define an abstract service provider. It is a set of Puppet modules designed to work together to provide to sysadmins everything they need to manage a service provider infrastructure that provides secure communication services. + +Getting started +============================= + +It is highly recommended that you start by reading the overview of the [LEAP Platform](https://leap.se/docs/platform) and then begin with the [Quick Start tutorial](https://leap.se/en/docs/platform/tutorials/quick-start) to walk through a test environment setup to get familiar with how things work before deploying to live servers. + +An offline copy of this documentation is contained in the `doc` subdirectory. For more current updates to the documentation, visit the website. + +Requirements +------------------ + +For testing a virtual deployment simulated on your computer, you will need a fairly recent computer x86_64 with hardware virtualization features (AMD-V or VT-x) and plenty of RAM. If you follow the "Quick Start" documentation we will walk you through using Vagrant to setup a test deployment. + +For a live deployment of the platform, the number of servers that is required depends on your needs and which services you want to deploy. At the moment, the LEAP Platform supports servers with a base Debian Wheezy installation. + +Troubleshooting +============================= + +If you have a problem, we are interested in fixing it! + +If you have a problem, be sure to have a look at the [Known Issues](https://leap.se/docs/platform/known-issues) to see if your issue is detailed there. + +If not, the best way for us to solve your problem is if you provide to us the complete log of what you did, and the output that was produced. Please don't cut out what appears to be useless information and only include the error that you received, instead copy and paste the complete log so that we can better determine the overall situation. If you can run the same command that produced the error with a raised verbosity level (such as -v2), that provides us with more useful debugging information. + +To capture the log, you can copy from the console, or run `leap --log FILE` or edit Leapfile to include `@log = '/tmp/leap.log'`. + +Visit https://leap.se/en/docs/get-involved/communication for details on how to contact the developers. + +Known issues +============ + +The following issues are known to exist in 0.5.2 and later: + +CouchDB Sync +------------ +You can't deploy new couchdb nodes after one or more have been deployed. Make *sure* that you configure and deploy all your couchdb nodes when first creating your provider. The problem is that we dont not have a clean way of adding couch nodes after initial creation of the databases, so any nodes added after result in improperly synchronized data. See Bug [#5601](https://leap.se/code/issues/5601) for more information. + +User setup and ssh +------------------ + +. if you aren't using a single ssh key, but have different ones, you will need to define the following at the top of your ~/.ssh/config: + HostName <ip address> + IdentityFile <path to identity file> + + (see: https://leap.se/code/issues/2946 and https://leap.se/code/issues/3002) + +. If the ssh host key changes, you need to run node init again (see: https://leap.se/en/docs/platform/guide#Working.with.SSH) + +. At the moment, only ECDSA ssh host keys are supported. If you get the following error: `= FAILED ssh-keyscan: no hostkey alg (must be missing an ecdsa public host key)` then you should confirm that you have the following line defined in your server's **/etc/ssh/sshd_config**: `HostKey /etc/ssh/ssh_host_ecdsa_key`. If that file doesn't exist, run `ssh-keygen -t ecdsa -f /etc/ssh/ssh_host_ecdsa_key -N ""` in order to create it. If you made a change to your sshd_config, then you need to run `/etc/init.d/ssh restart` (see: https://leap.se/code/issues/2373) + +. To remove an admin's access to your servers, please remove the directory for that user under the `users/` subdirectory in your provider directory and then remove that user's ssh keys from files/ssh/authorized_keys. When finished you *must* run a `leap deploy` to update that information on the servers. + +. At the moment, it is only possible to add an admin who will have access to all LEAP servers (see: https://leap.se/code/issues/2280) + +. leap add-user --self allows only one key - if you run that command twice with different keys, you will just replace the key with the second key. To add a second key, add it manually to files/ssh/authorized_keys (see: https://leap.se/code/issues/866) + + +Deploying +--------- + +. If you have any errors during a run, please try to deploy again as this often solves non-deterministic issues that were not uncovered in our testing. Please re-deploy with `leap -v2 deploy` to get more verbose logs and capture the complete output to provide to us for debugging. + +. If when deploying your debian mirror fails for some reason, network anomoly or the mirror itself is out of date, then platform deployment will not succeed properly. Check the mirror is up and try to deploy again when it is resolved (see: https://leap.se/code/issues/1091) + +. Deployment gives 'error: in `%`: too few arguments (ArgumentError)' - this is because you attempted to do a deploy before initializing a node, please initialize the node first and then do a deploy afterwards (see: https://leap.se/code/issues/2550) + +. This release has no ability to custom configure apt sources or proxies (see: https://leap.se/code/issues/1971) + +. When running a deploy at a verbosity level of 2 and above, you will notice puppet deprecation warnings, these are known and we are working on fixing them + +Special Environments +-------------------- + +. When deploying to OpenStack release "nova" or newer, you will need to do an initial deploy, then when it has finished run `leap facts update` and then deploy again (see: https://leap.se/code/issues/3020) + +leap-mx +------- + +. see https://github.com/leapcode/leap_mx#070 for issues regarding leap_mx + + +Contributing +============ + +In order to validate the syntax and style guide compliance +before you commit, see https://github.com/pixelated-project/puppet-git-hooks#installation + + +Changes +========= + +Read CHANGES.md or run `git log`. + +Authors and Credits +=================== + +See contributors: + + git shortlog -es --all + + +Copyright/License +================= + +Read LICENSE |