README
1NAME
2
3 Mojolicious::Plugin::SetUserGroup - Mojolicious plugin to set
4 unprivileged credentials
5
6SYNOPSIS
7
8 # Mojolicious
9 $self->plugin(SetUserGroup => {user => $user, group => $group});
10
11 # Mojolicious::Lite
12 plugin SetUserGroup => {user => $user, group => $group};
13
14 # Production mode only
15 plugin SetUserGroup => {user => $user, group => $group}
16 if $self->mode eq 'production';
17
18 # Root only
19 plugin SetUserGroup => {user => $user, group => $group}
20 if $> == 0;
21
22DESCRIPTION
23
24 This plugin is intended to replace the setuidgid functionality of
25 Mojo::Server. It should be loaded in application startup and it will
26 change the user and group credentials of the process when Mojo::IOLoop
27 is started, which occurs in each worker process of a
28 Mojo::Server::Prefork daemon like hypnotoad.
29
30 This allows an application to be started as root so it can bind to
31 privileged ports such as port 80 or 443, but run worker processes as
32 unprivileged users. However, if the application is not started as root,
33 it will most likely fail to change credentials. So, you should only set
34 the user/group when the application is started as root or a user with
35 the CAP_SETUID and CAP_SETGID capabilities(7).
36
37 This plugin only works on systems with a concept of Unix users and
38 groups, such as Linux, OS X, or BSD.
39
40 The morbo development server is currently incompatible with this plugin
41 as the lowered credentials causes the application worker to shut down.
42 Make sure credential changes do not occur when running your application
43 under morbo, either by not registering the plugin under that condition,
44 or starting morbo under the target user and group so no change occurs.
45
46METHODS
47
48 Mojolicious::Plugin::SetUserGroup inherits all methods from
49 Mojolicious::Plugin and implements the following new ones.
50
51 register
52
53 $plugin->register(Mojolicious->new, {user => $user, group => $group});
54
55 Install callback to change process credentials on the next Mojo::IOLoop
56 tick. If option user is undefined or the current user and group are
57 already correct, no credential change will occur. If option group is
58 undefined but user is defined, the group will be set to a group
59 matching the user name. If credential changes fail, an error will be
60 logged and the process will be stopped.
61
62AUTHOR
63
64 Dan Book, dbook@cpan.org
65
66CONTRIBUTORS
67
68 Jan Henning Thorsen (jhthorsen)
69
70 Lee Johnson (leejo)
71
72COPYRIGHT AND LICENSE
73
74 Copyright 2015, Dan Book.
75
76 This library is free software; you may redistribute it and/or modify it
77 under the terms of the Artistic License version 2.0.
78
79SEE ALSO
80
81 Mojolicious, POSIX, Unix::Groups::FFI
82
83