mirror of
https://github.com/ansible/awx.git
synced 2026-02-01 09:38:10 -03:30
Spelling and codespelling corrections from community PR
- Made the choice not to pull in the CI tools due to the possibility of it blocking PRs. Co-Authored By: Lila Yasin <89486372+djyasin@users.noreply.github.com>
This commit is contained in:
Joel Tenta
Lila Yasin
@@ -7,13 +7,12 @@ Session authentication is a safer way of utilizing HTTP(S) cookies. Theoreticall
|
||||
information from the cookie payload.
|
||||
|
||||
Session authentication, on the other hand, sets a single `awx_sessionid` cookie. The `awx_sessionid`
|
||||
is *a random string which will be mapped to user authentication information by the server*. Crackers who
|
||||
is _a random string which will be mapped to user authentication information by the server_. Crackers who
|
||||
hijack cookies will only get the `awx_sessionid` itself, which does not imply any critical user info, is valid only for
|
||||
a limited time, and can be revoked at any time.
|
||||
|
||||
> Note: The CSRF token will by default allow HTTP. To increase security, the `CSRF_COOKIE_SECURE` setting should
|
||||
be set to True.
|
||||
|
||||
> Note: The CSRF token will by default allow HTTP. To increase security, the `CSRF_COOKIE_SECURE` setting should
|
||||
> be set to True.
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -27,14 +26,16 @@ to `/api/login/` to actually log the user in. The return code of a successful lo
|
||||
successful login, the browser will be redirected; the redirected destination is determined by the `next` form
|
||||
item described below.
|
||||
|
||||
It should be noted that the POST body of `/api/login/` is *not* in JSON, but in HTTP form format. Four items should
|
||||
It should be noted that the POST body of `/api/login/` is _not_ in JSON, but in HTTP form format. Four items should
|
||||
be provided in the form:
|
||||
* `username`: The username of the user trying to log in.
|
||||
* `password`: The password of the user trying to log in.
|
||||
* `next`: The path of the redirect destination, in API browser `"/api/"` is used.
|
||||
* `csrfmiddlewaretoken`: The CSRF token, usually populated by using Django template `{% csrf_token %}`.
|
||||
|
||||
- `username`: The username of the user trying to log in.
|
||||
- `password`: The password of the user trying to log in.
|
||||
- `next`: The path of the redirect destination, in API browser `"/api/"` is used.
|
||||
- `csrfmiddlewaretoken`: The CSRF token, usually populated by using Django template `{% csrf_token %}`.
|
||||
|
||||
The `awx_session_id` is provided as a return `Set-Cookie` header. Here is a typical one:
|
||||
|
||||
```
|
||||
Set-Cookie: awx_sessionid=lwan8l5ynhrqvps280rg5upp7n3yp6ds; expires=Tue, 21-Nov-2017 16:33:13 GMT; httponly; Max-Age=1209600; Path=/
|
||||
```
|
||||
@@ -49,10 +50,11 @@ The name of the cookie is configurable by Tower Configuration setting `SESSION_C
|
||||
|
||||
The duration of the cookie is configurable by Tower Configuration setting `SESSION_COOKIE_AGE` under
|
||||
category `authentication`. It is an integer denoting the number of seconds the session cookie should
|
||||
live. The default session cookie age is two weeks.
|
||||
live. The default session cookie age is two weeks.
|
||||
|
||||
After a valid session is acquired, a client should provide the `awx_sessionid` as a cookie for subsequent requests
|
||||
in order to be authenticated. For example:
|
||||
|
||||
```
|
||||
Cookie: awx_sessionid=lwan8l5ynhrqvps280rg5upp7n3yp6ds; ...
|
||||
```
|
||||
@@ -74,17 +76,16 @@ invalidated sessions. If a client finds its session in that list, it should try
|
||||
Unlike tokens, sessions are meant to be short-lived and UI-only; therefore, whenever a user's password
|
||||
is updated, all sessions she owned will be invalidated and deleted.
|
||||
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
* Users should be able to log in via the `/api/login/` endpoint by correctly providing all necessary fields.
|
||||
* Logged-in users should be able to authenticate themselves by providing correct session auth info.
|
||||
* Logged-in users should be able to log out via `/api/logout/`.
|
||||
* The duration of a session cookie should be configurable by `SESSION_COOKIE_AGE`.
|
||||
* The maximum number of concurrent login for one user should be configurable by `SESSIONS_PER_USER`,
|
||||
- Users should be able to log in via the `/api/login/` endpoint by correctly providing all necessary fields.
|
||||
- Logged-in users should be able to authenticate themselves by providing correct session auth info.
|
||||
- Logged-in users should be able to log out via `/api/logout/`.
|
||||
- The duration of a session cookie should be configurable by `SESSION_COOKIE_AGE`.
|
||||
- The maximum number of concurrent login for one user should be configurable by `SESSIONS_PER_USER`,
|
||||
and over-limit user sessions should be warned by websocket.
|
||||
* When a user's password is changed, all her sessions should be invalidated and deleted.
|
||||
* User should not be able to authenticate by HTTPS(S) request nor websocket connection using invalid
|
||||
- When a user's password is changed, all her sessions should be invalidated and deleted.
|
||||
- User should not be able to authenticate by HTTPS(S) request nor websocket connection using invalid
|
||||
sessions.
|
||||
* No existing behavior, like job runs, inventory updates or callback receiver, should be affected
|
||||
- No existing behavior, like job runs, inventory updates or callback receiver, should be affected
|
||||
by session auth.
|
||||
|
||||
@@ -7,7 +7,7 @@ provisioned on-demand as a Pod that exists only for the duration of
|
||||
the playbook run. This is known as the ephemeral execution model and
|
||||
ensures a clean environment for every job run.
|
||||
|
||||
In some cases it is desireable to have the execution environment be "always-on",
|
||||
In some cases it is desirable to have the execution environment be "always-on",
|
||||
this is is done by manually creating an instance through the AWX API or UI.
|
||||
|
||||
|
||||
|
||||
@@ -94,7 +94,7 @@ In the above example, the search is limited to the "US-East" inventory and
|
||||
hosts with a name containing "nyc".
|
||||
|
||||
|
||||
### Acceptance Critera
|
||||
### Acceptance Criteria
|
||||
|
||||
When verifying acceptance, ensure the following statements are true:
|
||||
``
|
||||
|
||||
@@ -14,6 +14,6 @@ The CLI entry point `ansible-inventory` was introduced in Ansible 2.4. Inventory
|
||||
|
||||
## Writing Your Own Inventory File
|
||||
|
||||
You can add an SCM inventory source that points to your own yaml file which specifies an inventory plugin. You can also apply a credential of a `managed` type to that inventory source that matches the credential you are using. For example, you could have an inventory file for the `amazon.aws.aws_ec2` plugin and use the build-in `aws` credential type.
|
||||
You can add an SCM inventory source that points to your own yaml file which specifies an inventory plugin. You can also apply a credential of a `managed` type to that inventory source that matches the credential you are using. For example, you could have an inventory file for the `amazon.aws.aws_ec2` plugin and use the built-in `aws` credential type.
|
||||
|
||||
All built-in sources provide _secrets_ via environment variables. These can be re-used for SCM-based inventory, and your inventory file can be used to specify non-sensitive configuration details such as the `keyed_groups` (to provide) or `hostvars` (to construct).
|
||||
|
||||
@@ -158,7 +158,7 @@ Now that your model is a resource and has a `Role` defined, you can begin to acc
|
||||
>>> user = User.objects.first()
|
||||
>>> user in document.read_role
|
||||
False # not accessible by default
|
||||
>>> document.readonly_role.memebers.add(user)
|
||||
>>> document.readonly_role.members.add(user)
|
||||
>>> user in document.read_role
|
||||
True # now it is accessible
|
||||
>>> user in document.admin_role
|
||||
|
||||
@@ -48,7 +48,6 @@ A list of _valid_ zone identifiers (which can vary by system) can be found at:
|
||||
...
|
||||
]
|
||||
|
||||
|
||||
## UNTIL and Timezones
|
||||
|
||||
`DTSTART` values provided to AWX _must_ provide timezone information (they may
|
||||
@@ -58,26 +57,25 @@ Additionally, RFC5545 specifies that:
|
||||
|
||||
> Furthermore, if the "DTSTART" property is specified as a date with local
|
||||
> time, then the UNTIL rule part MUST also be specified as a date with local
|
||||
> time. If the "DTSTART" property is specified as a date with UTC time or
|
||||
> time. If the "DTSTART" property is specified as a date with UTC time or
|
||||
> a date with local time and time zone reference, then the UNTIL rule part
|
||||
> MUST be specified as a date with UTC time.
|
||||
|
||||
Given this, `RRULE` values that specify `UNTIL` datetimes must *always* be in UTC.
|
||||
Given this, `RRULE` values that specify `UNTIL` datetimes must _always_ be in UTC.
|
||||
|
||||
Valid:
|
||||
`DTSTART:20180601T120000Z RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000Z`
|
||||
`DTSTART;TZID=America/New_York:20180601T120000 RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000Z`
|
||||
`DTSTART:20180601T120000Z RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000Z`
|
||||
`DTSTART;TZID=America/New_York:20180601T120000 RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000Z`
|
||||
|
||||
Not Valid:
|
||||
|
||||
`DTSTART:20180601T120000Z RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000`
|
||||
`DTSTART;TZID=America/New_York:20180601T120000 RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000`
|
||||
|
||||
|
||||
## Previewing Schedules
|
||||
|
||||
AWX provides an endpoint for previewing the future dates and times for
|
||||
a specified `RRULE`. A list of the next _ten_ occurrences will be returned in
|
||||
a specified `RRULE`. A list of the next _ten_ occurrences will be returned in
|
||||
local and UTC time:
|
||||
|
||||
POST https://tower-host.example.org/api/v2/schedules/preview/
|
||||
@@ -107,42 +105,40 @@ local and UTC time:
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
## RRULE Limitations
|
||||
|
||||
AWX implements the following constraints on top of the `RFC5545` specification:
|
||||
|
||||
* The RRULE must start with the `DTSTART` attribute
|
||||
* At least one `RRULE` entry must be in the rrule
|
||||
* Strings with more than a single `DTSTART:` component are prohibited
|
||||
* The use of `RDATE` or `EXDATE`is prohibited
|
||||
* For any of the rules in the rrule:
|
||||
* `Interval` must be included
|
||||
* The use of `FREQ=SECONDLY` is prohibited
|
||||
* The usage of a `BYDAY` with a prefixed number is prohibited
|
||||
* The usage of both `COUNT` and `UNTIL` in the same rule is prohibited
|
||||
* The use of `COUNT=` with a value over 999 is prohibited
|
||||
- The RRULE must start with the `DTSTART` attribute
|
||||
- At least one `RRULE` entry must be in the rrule
|
||||
- Strings with more than a single `DTSTART:` component are prohibited
|
||||
- The use of `RDATE` or `EXDATE`is prohibited
|
||||
- For any of the rules in the rrule:
|
||||
- `Interval` must be included
|
||||
- The use of `FREQ=SECONDLY` is prohibited
|
||||
- The usage of a `BYDAY` with a prefixed number is prohibited
|
||||
- The usage of both `COUNT` and `UNTIL` in the same rule is prohibited
|
||||
- The use of `COUNT=` with a value over 999 is prohibited
|
||||
|
||||
## Implementation Details
|
||||
|
||||
Any time an `awx.model.Schedule` is saved with a valid `rrule` value, the
|
||||
`dateutil` library is used to burst out a list of all occurrences. From here,
|
||||
`dateutil` library is used to burst out a list of all occurrences. From here,
|
||||
the following dates are saved in the database:
|
||||
|
||||
* `main_schedule.rrule` - the original `RRULE` string provided by the user
|
||||
* `main_schedule.dtstart` - the _first_ datetime in the list of all occurrences (coerced to UTC)
|
||||
* `main_schedule.dtend` - the _last_ datetime in the list of all occurrences (coerced to UTC)
|
||||
* `main_schedule.next_run` - the _next_ datetime in list after `utcnow()` (coerced to UTC)
|
||||
- `main_schedule.rrule` - the original `RRULE` string provided by the user
|
||||
- `main_schedule.dtstart` - the _first_ datetime in the list of all occurrences (coerced to UTC)
|
||||
- `main_schedule.dtend` - the _last_ datetime in the list of all occurrences (coerced to UTC)
|
||||
- `main_schedule.next_run` - the _next_ datetime in list after `utcnow()` (coerced to UTC)
|
||||
|
||||
AWX makes use of [Celery Periodic Tasks
|
||||
(celerybeat)](http://docs.celeryproject.org/en/latest/userguide/periodic-tasks.html)
|
||||
to run a periodic task that discovers new jobs that need to run at a regular
|
||||
interval (by default, every 30 seconds). When this task starts, it queries the
|
||||
interval (by default, every 30 seconds). When this task starts, it queries the
|
||||
database for Schedules where `Schedule.next_run` is between
|
||||
`scheduler_last_runtime()` and `utcnow()`. For each of these, a new job is
|
||||
`scheduler_last_runtime()` and `utcnow()`. For each of these, a new job is
|
||||
launched, and `Schedule.next_run` is changed to the next chronological datetime
|
||||
in the list of all occurences.
|
||||
|
||||
in the list of all occurrences.
|
||||
|
||||
## Complex RRULE Examples
|
||||
|
||||
@@ -161,5 +157,3 @@ Every 15 minutes Monday to Friday from 10:01am to 6:02pm (inclusive):
|
||||
Any Saturday whose month day is between 12 and 18:
|
||||
|
||||
DTSTART:20191219T130551Z RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=SA;BYMONTHDAY=12,13,14,15,16,17,18
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user