From b0f6e01fa694c5ae54257b65f56a26fadc7f02e3 Mon Sep 17 00:00:00 2001 From: Stig Sandbeck Mathisen Date: Tue, 4 Jun 2019 18:06:00 +0200 Subject: [PATCH] Update README --- README.md | 83 +++++++++++++++++++++++-------------------------------- 1 file changed, 34 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 7c8bb76..88d0667 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,6 @@ # freeradius -Welcome to your new module. A short overview of the generated parts can be found in the PDK documentation at https://puppet.com/pdk/latest/pdk_generating_modules.html . - -The README template below provides a starting point with details about what information to include in your README. - #### Table of Contents 1. [Description](#description) @@ -18,71 +14,60 @@ The README template below provides a starting point with details about what info ## Description -Briefly tell users why they might want to use your module. Explain what your module does and what kind of problems users can solve with it. - -This should be a fairly short description helps the user decide if your module is what they want. +This is a module to install and manage +[FreeRADIUS](https://wiki.freeradius.org/Home). ## Setup -### What freeradius affects **OPTIONAL** - -If it's obvious what your module touches, you can skip this section. For example, folks can probably figure out that your mysql_instance module affects their MySQL instances. - -If there's more that they should know about, though, this is the place to mention: +### What freeradius affects -* Files, packages, services, or operations that the module will alter, impact, or execute. -* Dependencies that your module automatically installs. -* Warnings or other important notices. +The module manages: -### Setup Requirements **OPTIONAL** +* Packages needed for installing FreeRADIUS server and utilities. +* The freeradius service. +* The "mods-config/files/authorize" file, for user definitions and + defaults. -If your module requires anything extra before setting up (pluginsync enabled, another module, etc.), mention it here. - -If your most recent release breaks compatibility or requires particular steps for upgrading, you might want to include an additional "Upgrading" section here. +The rest is so far up to you. ### Beginning with freeradius -The very basic steps needed for a user to get the module up and running. This can include setup steps, if necessary, or it can be an example of the most basic use of the module. +Include the class, and provide a hash of concat::fragment resources +for the `$users` parameter. ## Usage -Include usage examples for common use cases in the **Usage** section. Show your users how to use your module to solve problems, and be sure to include code examples. Include three to five examples of the most important or common tasks a user can accomplish with your module. Show users how to accomplish more complex tasks that involve different types, classes, and functions working in tandem. - -## Reference - -This section is deprecated. Instead, add reference information to your code as Puppet Strings comments, and then use Strings to generate a REFERENCE.md in your module. For details on how to add code comments and generate documentation with Strings, see the Puppet Strings [documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) and [style guide](https://puppet.com/docs/puppet/latest/puppet_strings_style.html) - -If you aren't ready to use Strings yet, manually create a REFERENCE.md in the root of your module directory and list out each of your module's classes, defined types, facts, functions, Puppet tasks, task plans, and resource types and providers, along with the parameters for each. +The users are provided to the module as a hash of "concat::fragment" +resources. The important bits are the "content" and "order" +parameters. The "content" must contain one (or more) user definitions +for the radius "mods-config/files/authorize" file. -For each element (class, defined type, function, and so on), list: +Also, in this file, order matters. The concat resource will order the +fragments, you explicit using the . - * The data type, if applicable. - * A description of what the element does. - * Valid values, if the data type doesn't make it obvious. - * Default value, if any. -For example: +```puppet +$users = { + 'bob' => { + content => '"bob" Cleartext-Password := "hello"' + } +} -``` -### `pet::cat` - -#### Parameters - -##### `meow` - -Enables vocalization in your cat. Valid options: 'string'. - -Default: 'medium-loud'. +class { 'freeradius': + users => $users, +} ``` ## Limitations -In the Limitations section, list any incompatibilities, known issues, or other warnings. - -## Development +This module does not yet manage any other config than the "authorize" +file. -In the Development section, tell other users the ground rules for contributing to your project and how they should submit their work. +If you would like to manage anything other than the default +configuration of FreeRADIUS, which on Debian and Red Hat covers a +number of scenarios, manage these files explicitly, and notify +`Class['freeradius::service']` on changes. -## Release Notes/Contributors/Etc. **Optional** +## Development -If you aren't using changelog, put your release notes here (though you should consider using changelog). You can also add any additional sections you feel are necessary or important to include here. Please use the `## ` header. +This module lives on Github. Issues and pull requests are welcome.