plinker/nginx

Control Nginx as a reverse proxy through plinker RPC

PlinkerRPC - Nginx

The aim of this component is to build web forwards/reverse proxy to LXD/LXC containers on the host (or external upstreams), not as a server{} block configurator., _(*1)

The component uses nginx as a reverse proxy, it relies on php7-fpm being installed and will overwrite /etc/nginx/nginx.conf! So if you already have nginx installed then dont use this component as it will most likely break your stuff., _(*2)

Install

Require this package with composer using the following command:, _(*3)

``` bash $ composer require plinker/nginx, <sub>(*4)</sub>

Then navigate to `./vendor/plinker/nginx/scripts` and run `bash install.sh`.


## Client

Creating a client instance is done as follows:


    <?php
    require 'vendor/autoload.php';

    /**
     * Initialize plinker client.
     *
     * @param string $server - URL to server listener.
     * @param string $config - server secret, and/or a additional component data
     */
    $client = new \Plinker\Core\Client(
        'http://example.com/server.php',
        [
            'secret' => 'a secret password',
            // database connection
            'database' => [
                'dsn'      => 'sqlite:./.plinker/database.db',
                'host'     => '',
                'name'     => '',
                'username' => '',
                'password' => '',
                'freeze'   => false,
                'debug'    => false,
            ]
        ]
    );

    // or using global function
    $client = plinker_client('http://example.com/server.php', 'a secret password', [
        // database connection
        'database' => [
            'dsn'      => 'sqlite:./.plinker/database.db',
            'host'     => '',
            'name'     => '',
            'username' => '',
            'password' => '',
            'freeze'   => false,
            'debug'    => false,
        ]
    ]);


## Methods

Once setup, you call the class though its namespace to its method.


### Setup

Applies build tasks to plinker/tasks queue.

| Parameter   | Type           | Description   | Default        |
| ----------  | -------------  | ------------- |  ------------- | 
| options     | array          | Build options |                |

**Call**

    $client->nginx->setup([
        'build_sleep' => 5,
        'reconcile_sleep' => 5,
    ]);

**Response**
``` text

Update Package

Runs composer update to update package., <sub>(*5)</sub>

Call, <sub>(*6)</sub>

$client->nginx->update_package();

Response ``` text, <sub>(*7)</sub>

### Add

Add a web proxy rule.

| Parameter   | Type           | Description   | Default        |
| ----------  | -------------  | ------------- |  ------------- | 
| data        | array          | Rule data     |                |

**Call**

    $client->nginx->addBlock([
        'label' => 'My website nginx route',
        'ownDomain' => [
            'example.com',
            'www.example.com'
        ],
        'ownUpstream' => [
            ['ip' => '10.158.250.5', 'port' => '80']
        ],
        'letsencrypt' => 1,
        'enabled' => 1
    ]);

**Response**

``` text
Array
(
    [status] => success
    [values] => Array
        (
            [id] => 1
            [label] => My website nginx route
            [name] => c094c6c1-0fa1-40f1-af66-60e173e8dbac
            [ssl_type] => letsencrypt
            [added] => 2018-05-13 17:25:51
            [updated] => 2018-05-13 17:25:51
            [has_change] => 1
            [has_error] => 0
            [delete] => 0
            [enabled] => 1
            [update_ip] => 0
            [ip] => 10.158.250.5
            [port] => 80
            [ownDomain] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [name] => example.com
                            [route_id] => 1
                        )

                    [1] => Array
                        (
                            [id] => 2
                            [name] => www.example.com
                            [route_id] => 1
                        )

                )

            [ownUpstream] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [ip] => 10.158.250.5
                            [port] => 80
                            [route_id] => 1
                        )

                )

        )

)

Update Block

Update a web proxy rule., <sub>(*8)</sub>

Call, <sub>(*9)</sub>

client->nginx->update('name = ?', ['b2f78de7-5994-4c21-9c55-76cefe327a67'], [
    'label' => $test_route_label,
    'ownDomain' => [
        'updated-example.com',
        'www.updated-example.com'
    ],
    'ownUpstream' => [
        ['ip' => '10.158.250.5', 'port' => '80']
    ],
    'letsencrypt' => 0,
    'enabled' => 1
]);

Response, <sub>(*10)</sub>

``` text, <sub>(*11)</sub>

Array ( [status] => success [values] => Array ( [id] => 3 [label] => Example [name] => b2f78de7-5994-4c21-9c55-76cefe327a67 [ssl_type] => [added] => 2018-05-12 20:17:09 [updated] => 2018-05-13 17:28:50 [has_change] => 1 [has_error] => 1 [delete] => 0 [enabled] => 1 [update_ip] => 0 [ip] => 10.158.250.5 [port] => 80 [error] => {} [ownDomain] => Array ( [0] => Array ( [id] => 9 [name] => updated-example.com [route_id] => 3 ), <sub>(*12)</sub>

                [1] => Array
                    (
                        [id] => 10
                        [name] => www.updated-example.com
                        [route_id] => 3
                    )

            )

        [ownUpstream] => Array
            (
                [0] => Array
                    (
                        [id] => 5
                        [ip] => 10.158.250.5
                        [port] => 80
                        [route_id] => 3
                    )

            )

    )

), <sub>(*13)</sub>

### Remove

Remove web proxy rule.

| Parameter   | Type           | Description   | Default        |
| ----------  | -------------  | ------------- |  ------------- | 
| placeholder | string         | Query placeholder |            |
| values      | array          | Match values  |                |

**Call**

    ruleById(1)   - $client->nginx->remove('id = ?', [1]);
    ruleByName(1) - $client->nginx->remove('name = ?', ['guidV4-value'])

**Response**
``` text
Array
(
    [status] => success
)

Reset

Remove all web proxy rules., <sub>(*14)</sub>

Call, <sub>(*15)</sub>

$client->nginx->reset();     // remove just rules
$client->nginx->reset(true); // remove rules and tasks (purge)

Response ``` text Array ( [status] => success ), <sub>(*16)</sub>

### Fetch

Fetch currently configured web proxy rules from database.

| Parameter   | Type           | Description   | Default        |
| ----------  | -------------  | ------------- |  ------------- | 
| placeholder | string         | Query placeholder | |
| values      | array          | Match values  |              |

**Call**

    all           - $client->nginx->fetch();
    ruleById(1)   - $client->nginx->fetch('id = ?', [1]);
    ruleByName(1) - $client->nginx->fetch('name = ?', ['guidV4-value'])

**Response**
``` text
Array
(
    [0] => Array
        (
            [id] => 1
            [label] => Example
            [name] => 9801e216-a663-4f21-a3f5-047be2b3b9c9
            [ssl_type] => 
            [added] => 2018-05-12 19:52:58
            [updated] => 2018-05-12 19:52:58
            [has_change] => 0
            [has_error] => 0
            [delete] => 0
            [enabled] => 1
            [update_ip] => 0
            [ip] => 10.158.250.5
            [port] => 80
            [error] => 
            [ownDomain] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [name] => example.com
                            [route_id] => 2
                        )

                    [1] => Array
                        (
                            [id] => 2
                            [name] => www.example.com
                            [route_id] => 2
                        )

                )

            [ownUpstream] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [ip] => 10.158.250.5
                            [port] => 80
                            [route_id] => 2
                        )

                )

        )
)

Count

Fetch count of currently configured web proxy rules from database., <sub>(*17)</sub>

Call, <sub>(*18)</sub>

all           - $client->nginx->count();
ruleById(1)   - $client->nginx->count('id = ?', [1]);
ruleByName(1) - $client->nginx->count('name = ?', ['guidV4-value'])

Response ``` text 1, <sub>(*19)</sub>

### Rebuild

Rebuild web proxy rule.

| Parameter   | Type           | Description   | Default        |
| ----------  | -------------  | ------------- |  ------------- | 
| placeholder | string         | Query placeholder | |
| values      | array          | Match values  |              |

**Call**

    ruleById(1)   - $client->nginx->rebuild('id = ?', [1]);
    ruleByName(1) - $client->nginx->rebuild('name = ?', ['guidV4-value'])

**Response**
``` text
Array
(
    [status] => success
)

Status

Enumarate and return status of nginx connections., <sub>(*20)</sub>

Call, <sub>(*21)</sub>

$client->nginx->status();

Response, <sub>(*22)</sub>

text Array ( [active_connections] => 2 [accepts] => 579 [handled] => 579 [requests] => 579 [reading] => 0 [writing] => 2 [waiting] => 0 ), <sub>(*23)</sub>

Testing

There are no tests setup for this component., <sub>(*24)</sub>

Contributing

Please see CONTRIBUTING for details., <sub>(*25)</sub>

Security

If you discover any security related issues, please contact me via https://cherone.co.uk instead of using the issue tracker., <sub>(*26)</sub>

Credits

• Lawrence Cherone
• All Contributors

Development Encouragement

If you use this project and make money from it or want to show your appreciation, please feel free to make a donation https://www.paypal.me/lcherone, thanks., <sub>(*27)</sub>

Sponsors

Get your company or name listed throughout the documentation and on each github repository, contact me at https://cherone.co.uk for further details., <sub>(*28)</sub>

License

The MIT License (MIT). Please see License File for more information., <sub>(*29)</sub>

See the organisations page for additional components., <sub>(*30)</sub>