Convert README from rdoc to markdown
Also add CI badges
This commit is contained in:
Lars Kanis
parent
be9a5a7531
commit
02d7ad6756
87
README.md
Normal file
87
README.md
Normal file
@ -0,0 +1,87 @@
|
||||
[](https://travis-ci.org/larskanis/pg-ldap-sync) [](https://ci.appveyor.com/project/larskanis/pg-ldap-sync/branch/master)
|
||||
|
||||
# Use LDAP permissions in PostgreSQL
|
||||
|
||||
* http://github.com/larskanis/pg-ldap-sync
|
||||
|
||||
## DESCRIPTION:
|
||||
|
||||
LDAP is often used for a centralized user and role management in an enterprise environment.
|
||||
PostgreSQL offers different authentication methods, like LDAP, SSPI, GSSAPI or SSL.
|
||||
However, for any method the user must already exist in the database, before the authentication can be used.
|
||||
There is currently no direct authorization of database users on LDAP.
|
||||
So roles and memberships has to be administered twice.
|
||||
|
||||
This program helps to solve the issue by synchronizing users, groups and their memberships from LDAP to PostgreSQL.
|
||||
Access to LDAP is used read-only.
|
||||
`pg_ldap_sync` issues proper CREATE ROLE, DROP ROLE, GRANT and REVOKE commands to synchronize users and groups.
|
||||
|
||||
It is meant to be started as a cron job.
|
||||
|
||||
## FEATURES:
|
||||
|
||||
* Configurable per YAML config file
|
||||
* Can use Active Directory as LDAP-Server
|
||||
* Nested groups/roles supported
|
||||
* Set scope of considered users/groups on LDAP and PG side
|
||||
* Runs with pg.gem (C-library) or postgres-pr.gem (pure Ruby)
|
||||
* Test mode which doesn't do any changes to the DBMS
|
||||
* Both LDAP and PG connections can be secured by SSL/TLS
|
||||
|
||||
## REQUIREMENTS:
|
||||
|
||||
* Ruby-2.0+, JRuby-1.2, Rubinius-1.2 or better
|
||||
* LDAP-v3 server
|
||||
* PostgreSQL-server v9.0+
|
||||
|
||||
## INSTALL:
|
||||
|
||||
Install Ruby:
|
||||
|
||||
* on Windows: http://rubyinstaller.org
|
||||
* on Debian/Ubuntu: `apt-get install ruby libpq-dev`
|
||||
|
||||
Install pg-ldap-sync and required dependencies:
|
||||
```sh
|
||||
gem install pg-ldap-sync
|
||||
```
|
||||
|
||||
### Install from Git:
|
||||
```sh
|
||||
git clone https://github.com/larskanis/pg-ldap-sync.git
|
||||
cd pg-ldap-sync
|
||||
bundle
|
||||
rake install
|
||||
```
|
||||
|
||||
## USAGE:
|
||||
|
||||
Create a config file based on
|
||||
[config/sample-config.yaml](https://github.com/larskanis/pg-ldap-sync/blob/master/config/sample-config.yaml)
|
||||
or even better
|
||||
[config/sample-config2.yaml](https://github.com/larskanis/pg-ldap-sync/blob/master/config/sample-config2.yaml)
|
||||
|
||||
Run in test-mode:
|
||||
```sh
|
||||
pg_ldap_sync -c my_config.yaml -vv -t
|
||||
```
|
||||
Run in modify-mode:
|
||||
```sh
|
||||
pg_ldap_sync -c my_config.yaml -vv
|
||||
```
|
||||
|
||||
## TEST:
|
||||
There is a small test suite in the `test` directory that runs against an internal ruby-ldapserver and PostgreSQL server. Ensure gem `ruby-ldapserver` is installed and `pg_ctl`, `initdb` and `psql` commands are in the `PATH`. Then:
|
||||
```sh
|
||||
cd pg-ldap-sync
|
||||
rake test
|
||||
```
|
||||
|
||||
## ISSUES:
|
||||
|
||||
* There is currently no way to set certain user attributes in PG based on individual attributes in LDAP (expiration date etc.)
|
||||
|
||||
|
||||
## License
|
||||
|
||||
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
||||
86
README.rdoc
86
README.rdoc
@ -1,86 +0,0 @@
|
||||
= Use LDAP permissions in PostgreSQL
|
||||
|
||||
* http://github.com/larskanis/pg-ldap-sync
|
||||
|
||||
== DESCRIPTION:
|
||||
|
||||
LDAP is often used for a centralized user and role management
|
||||
in an enterprise environment. PostgreSQL offers different
|
||||
authentication methods, like LDAP, SSPI, GSSAPI or SSL.
|
||||
However, for any method the user must already exist in the database,
|
||||
before the authentication can be used. There is currently
|
||||
no direct authorization of database users on LDAP. So roles
|
||||
and memberships has to be administered twice.
|
||||
|
||||
This program helps to solve the issue by synchronizing users,
|
||||
groups and their memberships from LDAP to PostgreSQL.
|
||||
Access to LDAP is used read-only. <tt>pg_ldap_sync</tt> issues proper
|
||||
CREATE ROLE, DROP ROLE, GRANT and REVOKE commands to synchronize
|
||||
users and groups.
|
||||
|
||||
It is meant to be started as a cron job.
|
||||
|
||||
== FEATURES:
|
||||
|
||||
* Configurable per YAML config file
|
||||
* Can use Active Directory as LDAP-Server
|
||||
* Nested groups/roles supported
|
||||
* Set scope of considered users/groups on LDAP and PG side
|
||||
* Runs with pg.gem (C-library) or postgres-pr.gem (pure Ruby)
|
||||
* Test mode which doesn't do any changes to the DBMS
|
||||
* Both LDAP and PG connections can be secured by SSL/TLS
|
||||
|
||||
== REQUIREMENTS:
|
||||
|
||||
* Ruby-2.0+, JRuby-1.2, Rubinius-1.2 or better
|
||||
* LDAP-v3 server
|
||||
* PostgreSQL-server v9.0+
|
||||
|
||||
== INSTALL:
|
||||
|
||||
Install Ruby:
|
||||
* on Windows: http://rubyinstaller.org
|
||||
* on Debian/Ubuntu: <tt>apt-get install ruby libpq-dev</tt>
|
||||
|
||||
Install pg-ldap-sync and required dependencies:
|
||||
gem install pg-ldap-sync
|
||||
|
||||
=== Install from Git:
|
||||
git clone https://github.com/larskanis/pg-ldap-sync.git
|
||||
cd pg-ldap-sync
|
||||
bundle
|
||||
rake install
|
||||
|
||||
== USAGE:
|
||||
|
||||
Create a config file based on
|
||||
{config/sample-config.yaml}[https://github.com/larskanis/pg-ldap-sync/blob/master/config/sample-config.yaml]
|
||||
or even better
|
||||
{config/sample-config2.yaml}[https://github.com/larskanis/pg-ldap-sync/blob/master/config/sample-config2.yaml]
|
||||
|
||||
Run in test-mode:
|
||||
|
||||
pg_ldap_sync -c my_config.yaml -vv -t
|
||||
|
||||
Run in modify-mode:
|
||||
|
||||
pg_ldap_sync -c my_config.yaml -vv
|
||||
|
||||
|
||||
== TEST:
|
||||
There is a small test suite in the <tt>test</tt> directory that runs
|
||||
against an internal ruby-ldapserver and PostgreSQL server. Ensure gem
|
||||
<tt>ruby-ldapserver</tt> is installed and <tt>pg_ctl</tt>, <tt>initdb</tt> and <tt>psql</tt>
|
||||
commands are in the <tt>PATH</tt>. Then:
|
||||
|
||||
cd pg-ldap-sync
|
||||
rake test
|
||||
|
||||
== ISSUES:
|
||||
* There is currently no way to set certain user attributes in PG
|
||||
based on individual attributes in LDAP (expiration date etc.)
|
||||
|
||||
|
||||
== License
|
||||
|
||||
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
||||
@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
|
||||
spec.bindir = "exe"
|
||||
spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
|
||||
spec.require_paths = ["lib"]
|
||||
spec.rdoc_options = %w[--main README.md --charset=UTF-8]
|
||||
|
||||
spec.add_runtime_dependency "net-ldap", "~> 0.16"
|
||||
spec.add_runtime_dependency "kwalify", "~> 0.7"
|
||||
|
||||
Reference in New Issue
Block a user