https://k5wiki.kerberos.org/w/api.php?action=feedcontributions&user=Ghudson&feedformat=atomK5Wiki - User contributions [en]2024-03-29T04:37:20ZUser contributionsMediaWiki 1.27.4https://k5wiki.kerberos.org/wiki?title=Cleanups&diff=6040Cleanups2023-07-29T06:40:09Z<p>Ghudson: </p>
<hr />
<div>This page describes opportunities for internal code cleanups. Anything to do with a user-facing or developer-facing behavior should go elsewhere (perhaps in an RT ticket, or somewhere related to the roadmap).<br />
<br />
* sam2_process (preauth_sam2.c) should use a cleanup label instead of repeated free invocations. It is also long and should be broken up into smaller pieces if possible. (See [[Manual Testing]] for guidance on how to test at least part of this function.)<br />
<br />
* kadmind's main() should not have repeated blocks of calls to release resources. It's probably unnecessary to release resources on error exit (plenty of other programs don't bother).<br />
<br />
* The build system used to have multiple configure.in files making use of an aclocal.m4. Now that we only have one configure.in, we don't really need a separate aclocal.m4.<br />
<br />
* In the build system, some variables like INSTALL_PREFIX are just name variants of other variables and are only used in one or two places under the variant name.<br />
<br />
* Account lockout decision logic is duplicated in the DB2 and LDAP KDB modules.<br />
<br />
* The serialization framework has several levels of unnecessary nesting and should use a cleanup label rather than the repeated "if (!kret)" pattern.<br />
<br />
* lib/krb5/os appears to have a couple of different functions to generate ADDRTYPE_ADDRPORT addresses (one in mkfaddr.c and another in full_ipaddr.c).<br />
<br />
* klist and kinit (at least) still have some internal vestiges from when they supported krb4 and krb5 credentials, and could be simplified.<br />
<br />
* The kdcpreauth pluggable interface uses the new plugin support functions, but does not have a proper consumer interface as described in [[Projects/Plugin_support_improvements#Consumer_interface]].<br />
<br />
* It's no longer our practice to use krb5_x() to make calls through function pointers, but it's still used in ktfns.c.<br />
<br />
* The LDAP KDB module maintains a connection pool, but only ever uses one connection (since our KDC is single-threaded).<br />
<br />
* lib/gssapi/mechglue should use the MIT krb5 style, not the Solaris coding style with tabs.<br />
<br />
* lib/gssapi/generic contains some utility functions which are specific to the krb5 mech and should be located in lib/gssapi/krb5.<br />
<br />
* Some parameters in osconf.hin are unused (like KDC_PORTNAME, KRB5_DEFAULT_ADMIN_ACL, and DEFAULT_ADMIN_ACL).<br />
<br />
* kpropd's design can be simplified:<br />
** Currently, it forks to handle each incoming connection, but then waits for the child process. This could be done without forking, although doit() would have to be modified to avoid using exit() or an aborting SIGALRM handler.<br />
** Currently kpropd relies on dual-stack support to handle both IPv4 and IPv6 connections so that it can use a single blocking accept() call to wait for incoming connections. Some platforms such as OpenBSD don't have dual-stack support. We should open a listening socket for each address family and use libverto to wait for connections on both of them.<br />
** Currently, if iprop is enabled, a child process is used to handle incoming connections, but using libverto, the same process should be able to handle both. The process wouldn't ask for iprop updates while processing a kprop connection (since that handling is synchronous), but that should be okay.<br />
<br />
* The libkdb5 interface includes krb5_db_setup_lib_handle(), which has no caller-visible semantics (it is invoked internally when needed). That function can be removed from the interface, since we don't guarantee interface stability for that library.<br />
<br />
* krb5_db_get_age() and its associated DAL interface can be removed.<br />
<br />
* The krb5_db_entry "len" field has no caller-useful semantics. krb5_db_put_principal will abort with the DB2 back end if the len field is not set to the magic value KRB5_KDB_V1_BASE_LENGTH. This field and the associated constant can be removed.<br />
<br />
* The krb5_db_entry "n_tl_data" field is redundant with the length of the tl_data linked list, and isn't likely to have a significant performance impact since tl_data lists are short. It can be removed.<br />
<br />
* The constants KRB5_TL_KADM5_E_DATA, KRB5_TL_RB1_CHALLENGE, KRB5_TL_USER_CERTIFICATE, KRB5_TL_LM_KEY, and KRB5_TL_X509_SUBJECT_ISSUER_NAME are unused and can likely be removed.<br />
<br />
* The osa_policy_ent_rec "version" field has no caller-visible semantics; it is used internally by the DB2 module's xdr_osa_policy_ent_rec(), but a local variable would serve. The field can be removed.<br />
<br />
* adb_openclose.c maintains a static linked list mapping filenames to lock structures, in an attempt to work around bad POSIX file locking semantics. This list serves no useful purpose because there is no equivalent code for the main DB2 lockfile, and OFD locks (where they are available) are a much better solution. The list can be removed and the locking code simplified.<br />
<br />
* krb5_db_iter_policy takes a match_expr parameter and passes it through to the back end, but both back ends ignore it. The parameter can be removed.<br />
<br />
* add_to_history() in svr_principal.c stores password history entries in a circular queue, which is unnecessarily complicated because the data structure is serialized after every password change. We can simplify this code by always generating a list in sorted order, although we must remain bidirectionally compatible with the existing code. We can either sort the entries in the structure we read in, or we can use the old_key_next value to identify which nhist-2 entries to preserve.<br />
<br />
* alt_prof.c contains functions for opening krb5.conf and kdc.conf, and for translating string, boolean, deltat, and integer values. These are largely redundant with normal profile handling functions. (One difference: alt_prof.c selects the last relation for a single-valued field, while regular profile functions select the first one. This is probably ignorable.)<br />
<br />
* krb5_dbe_fetch_act_key_list is used only from kadmind, which immediately calls krb5_dbe_find_act_mkey and frees the list. This API could be replaced with an API to retrieve the active master key and its kvno, so that kadmind does not need to know about the existence of the master key activation list. The new API could also be used in kdb5_util's kdb5_update_princ_encryption in place of the three calls it uses to get the active master key.<br />
<br />
* krb5_free_cred_enc_part does not obey the usual contract, as it frees only the contents of the container passed in, not the container itself. It is not a public API, so its behavior can be changed as long as all of the in-tree callers are adjusted to match.<br />
<br />
* krb5_rd_req_decoded and krb5_rd_req_decoded_anyflags have unnecessary output parameters which receive a copy of the ticket. The ticket (with decrypted enc_part if we could decrypt it) is in req->ticket, so the caller does not need a copy. The following cleanups could simplify the code and slightly improve performance:<br />
** krb5_rd_req could pass a NULL ticket argument, and instead steal the ticket pointer before freeing request.<br />
** kg_accept_krb5 could pass a NULL ticket argument, and instead refer to request->ticket (possibly via an alias pointer).<br />
** kdc_rd_ap_req could have its ticket parameter removed. kdc_process_tgs_req could refer to apreq->ticket and could steal that pointer for its own ticket output parameter before freeing apreq.<br />
** Since krb5_rd_req_decoded/krb5_rd_req_decoded_anyflags are no longer public interfaces (they were purged in the great 1.2.2 cleanup, and their prototypes are completely gone from krb5.h since 1.7), we could rename them and remove their ticket output parameters.<br />
<br />
* pkinit_crypto_openssl.h does not need to be a header file. Its contents can be part of pkinit_crypto_openssl.c.<br />
<br />
* pkinit_identity_crypto_context contains a stack of certs (my_certs) and an index (cert_index), but the stack only ever contains one cert and the index is always 0.<br />
<br />
* pkinit_identity_crypto_context contains a cert collection with a different lifetime from the object itself, managed by crypto_load_certs() and crypto_free_cert_info(). The collection is only used briefly by pkinit_identity_initialize() and pkinit_identity_prompt(). It would be better represented with a separate object type, whose lifetime is managed via local variables in the pkinit_identity functions.<br />
<br />
* The PKINIT KDC and PKINIT client share a number of identity requirements such as anchors, intermediates, and CRLs, but they have rather different logic for certificates. The client can select from a collection of certs and may need to prompt for passwords in order to access private keys. The KDC never prompts for a password and has just one cert. The KDC code path would be easier to understand if it did not go through all of the same identity initialization interface as the client, with the anchor/intermediate/CRL implementation shared between the two via a helper function.<br />
<br />
* If k5_vset_error allowed a null ep parameter and did nothing (like krb5_set_error_message allows a null context), then callers of the plugins.c functions could be simplified when they don't want extended error information, as in the g_initialize.c macros.<br />
<br />
* The libprofile iterator logic around skip_num is not very intuitive and may not always be correct. iter->num counts up when a match is returned--that is, deleted nodes are not considered. If iter->num is used for skip_num because the file generation has changed, it counts down in the search loop *before* deleted nodes are ignored. This behavior is required for the first test in test_prof1 which deletes all nodes in an iterator, because the first call to profile_update_relation changes the file generation and also deletes the first matching node.<br />
<br />
* libprofile's prof_tree.c contains several copies of loops to search for a name in a node list, and its prof_set.c contains several copies of loops to look up parent sections. These could be factored out; however, the skip_num logic in profile_node_iterator currently prevents factoring out that copy of the search loop unless skip_num becomes a parameter of the factored-out helper function.<br />
<br />
* lib/kadm5/srv/server_acl.c contains many opportunities for cleanup:<br />
** The acl_*_msg string variables should be removed and their values inlined into the log statements.<br />
** The ae_ prefix on acl_entry field names is unnecessary.<br />
** The kadm5int_acl_ prefix on static functions is unnecessary.<br />
** The name, target, and restrictions strings could be evaluated immediately at parsing time.<br />
** A lot of code could be de-indented.<br />
** The ae_name_bad, ae_target_bad, and ae_restrictions_bad fields are redundant, as setting any of them results in setting ae_name_bad which disables the entry. They may wind up all being unnecessary if we stop doing lazy evaluation of those strings.<br />
** The structure of kadm5int_acl_parse_restrictions makes it difficult to identify which part of the restrictions string is invalid.<br />
** The file uses K&R-style function definitions.<br />
** Several functions operate multiple times on their output arguments, contrary to current practice.<br />
<br />
* kadm5_policy_t is a typedef for char *, representing a policy name. It is used in two prototypes in admin.h but not elsewhere. It should be replaced with const char * in those prototypes, and the typedef should be commented as being deprecated.<br />
<br />
* krb5_string_to_deltat() is implemented in libkrb5 using a bison grammar, which adds to the complexity of our repository and build system. It could be rewritten in C with no loss of clarity, as only a few interval formats are supported.<br />
<br />
* The library initialization support in k5-platform.h uses different strategies on Windows and POSIX platforms. Windows (as of Vista and Server 2008) supports a function InitOnceExecuteOnce() which works like pthread_once(). Using that function we could make a Windows version of k5_once() and use the same library initialization strategy on all platforms. Library finalization support would remain conditionalized by platform.<br />
<br />
* It is also possible to emulate static mutex initialization on Windows, using a wrapper lock function which does InterlockedCompareExchangePointer(), as detailed [http://stackoverflow.com/questions/3555859/is-it-possible-to-do-static-initialization-of-mutexes-in-windows here]. With static mutex initializers we might not need as many library initializers, although we would still need library finalizers to clean up any initialized mutexes.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Coding_style/Practices&diff=6039Coding style/Practices2023-07-22T22:11:23Z<p>Ghudson: /* Misc. to be sorted */</p>
<hr />
<div>__NOTOC__<br />
==Quick Summary==<br />
<br />
* Avoid strcpy, strcat, sprintf, and *scanf.<br />
* Use "goto cleanup" to ensure that resources are released on all function exit paths.<br />
* Keep track of which pointers are owners and which are aliases; initialize owner pointers to NULL.<br />
* Avoid creating structure instances containing a mix of owner and alias pointers.<br />
* Name output variables ending with "_out". Initialize them at the beginning of a function, then don't touch them until just before successful return.<br />
* Don't use assignments as truth values except (perhaps) in a while loop.<br />
* Use NULL for the null pointer and '\0' for the null character. Don't use pointers or characters as truth values.<br />
* Put braces around flow control statement bodies if they are more than one line long, and around any do-while loop.<br />
* Try to keep preprocessor statements outside of function bodies.<br />
* Avoid declarations of local variables in inner scope.<br />
* Parenthesize (sparingly) to avoid C precedence confusion, especially when using bitwise operators.<br />
* Use all-uppercase names for macros.<br />
* Avoid stepping on reserved C namespaces.<br />
* Use the krb5_ prefix for libkrb5 API functions, and the k5_ prefix for linker-visible internal functions. Don't use a prefix for static functions.<br />
* Don't use designated initializers or compound literals in code which is built on Windows.<br />
* Don't use variable-length arrays or alloca().<br />
* Avoid long or deeply nested function bodies. Use helpers to limit function complexity.<br />
* Function calls through pointers should look like "(*fp)(args)" or "vtable->method(vars)".<br />
* Always declare function return types. Use ANSI C-style function definitions.<br />
* Don't pass or return structures by value in API functions.<br />
* Precede functions with block comments describing what they do.<br />
* Make your code warning-clean under the gcc warning flags used in our build system.<br />
<br />
== String Handling ==<br />
<br />
Code should not use any of the following functions: strcpy, strcat, sprintf, or any *scanf function.<br />
<br />
Dynamically allocated buffers are preferred to fixed-sized buffers. When using dynamic buffers:<br />
* Use strdup or asprintf for simple constructions.<br />
* Use the k5buf module (k5-buf.h) for complex constructions. If this is not desirable, strlcpy and strlcat are valid alternatives.<br />
<br />
Substitute versions of strlcpy, strlcat, and asprintf, for operating systems that don't supply them, are declared in k5-platform.h and defined in the support library (which practically everything in the tree links directly against).<br />
<br />
When using fixed-sized buffers:<br />
* Use strlcpy for simple copies.<br />
* Use snprintf for simple compound constructions. Avoid using precision or field width specifiers in snprintf format strings.<br />
* To check for truncation when using snprintf, use the following approach:<br />
<pre><br />
result = snprintf(buffer, sizeof(buffer), "format string", ...);<br />
if (SNPRINTF_OVERFLOW(result, sizeof(buffer))<br />
handle_overflow_error;<br />
</pre><br />
The SNPRINTF_OVERFLOW macro is defined in k5-platform.h.<br />
<br />
=== Current conformance ===<br />
<br />
Existing code mostly conforms, with some exceptions.<br />
<br />
=== Rationale ===<br />
<br />
It is relatively common to audit a code base such as krb5 and flag all uses of strcpy and similar functions, even if they are used safely. Verifying that the function is used safely requires manual inspection. Using safer alternatives does not guarantee code safety, but does reduce the likelihood of a catastrophic buffer overflow vulnerability.<br />
<br />
In some compilation environments under Solaris, field widths and precisions are computed using screen columns rather than bytes.<br />
<br />
sprintf returns a signed integer; buffer sizes are typically size_t (which is an unsigned type). Comparing the two directly will result in a warning from some compilers, and has unpredictable semantics depending on the relative widths of int and size_t. Also, some sprintf implementations, such as the one in Solaris prior to version 10, return -1 on a buffer overflow, whereas the C99 behavior returns the number of bytes which would have been written to the string. The SNPRINTF_OVERFLOW macro uses casts to address both issues.<br />
<br />
The k5buf module safely allows multi-step string construction within fixed-size or dynamic buffers without performing an error check on each append, and without pre-computing lengths. Errors need only be checked when the resulting string needs to be read or handed off to another function.<br />
<br />
== Exception Handling ==<br />
<br />
If a function allocates several resources and has many exit paths, use the following general structure when possible:<br />
<br />
<pre><br />
{<br />
krb5_error_code ret;<br />
char *ptr1 = NULL;<br />
krb5_blah *ptr2 = NULL;<br />
<br />
...<br />
ret = another_function(...);<br />
if (ret)<br />
goto cleanup;<br />
...<br />
cleanup:<br />
free(ptr1);<br />
krb5_free_blah(ptr2);<br />
return ret;<br />
}<br />
</pre><br />
<br />
(free() and krb5_free_foo() functions will both accept NULL as input and do nothing.) Simpler functions may use simpler control structures, but do not get to the point of freeing the same resource in several different places within a function depending on the exit path. Do not use multiple exit labels.<br />
<br />
Unless constrained by an API standard such as GSSAPI, functions which can fail should return a krb5_error_code. Error codes are defined in com_err tables, usually located in src/lib/krb5/error_tables.<br />
<br />
Functions can also set extended error messages using krb5_set_error_message() (or, in dependencies of libkrb5, krb5int_set_error() on &context->err). Code should set extended error messages when an error condition is moderately likely to occur and the default string for the error code is insufficiently clear. Avoid exposing function names and other implementation details in error messages.<br />
<br />
After ignoring or handling an error code, krb5_clear_error_message() (or krb5int_clear_error()) should be used to ensure that an extended error message is not applied erroneously to a later instance of the same error code. This can be especially important in loops.<br />
<br />
=== Current conformance ===<br />
<br />
Existing code mostly conforms, with some exceptions.<br />
<br />
=== Rationale ===<br />
<br />
The "goto cleanup" flow control is the most reliable way to avoid resource leaks within the constraints of the krb5 code base. Within libraries, the code base does not abort on memory allocation failure, so tends to have many exit paths within some functions.<br />
<br />
Extended error messages can provide invaluable information about error conditions, but merely serve to expand code if used mechanically.<br />
<br />
== Memory management ==<br />
<br />
An allocated object can have multiple pointers to it. The pointer through which the object will eventually be freed is called the owner, and other pointers to the object are called aliases. The owner may change over the lifetime of the object.<br />
<br />
When transferring ownership of a pointer (such as when returning an allocated value to a caller via an output parameter), null out the old owner pointer unless it is about to be destroyed or go out of scope.<br />
<br />
Avoid mixing owner pointers and aliases within a structure. Create additional local variables to act as owner pointers when this situation occurs.<br />
<br />
Initialize variables containing owner pointers to NULL. Free the pointed-to objects (unconditionally, when possible) in the function's cleanup handler.<br />
<br />
In some cases these rules may not be reasonable; for instance, temporary memory allocated within a loop body must be freed within the loop body, not in the cleanup handler. Break these rules when necessary, but also make liberal use of helper functions to simplify memory management.<br />
<br />
=== Current conformance ===<br />
<br />
Newer code mostly conforms; older code does not.<br />
<br />
=== Rationale ===<br />
<br />
Following these rules makes it easier to verify that a function contains no memory leaks, no double frees, and no dereferences after frees. These rules also keep memory management logic out of the core logic of a function, making it easier to understand.<br />
<br />
== Output parameter handling ==<br />
<br />
Output parameter names should typically end in "_out". Output parameters should typically be the last parameters to a function, with certain exceptions (such as context-like parameters).<br />
<br />
Avoid filling in a caller-allocated structure. Instead, allocate the structure within the function and output a pointer to the structure.<br />
<br />
If a function has output parameters, their values should be defined in all cases, including on failure. Most of the time, this means setting output parameters to NULL or zero at the beginning of the function, and not assigning real values to the output parameters until successful completion from the function is guaranteed. A typical function with output parameters should look something like:<br />
<br />
<pre><br />
krb5_error_code<br />
function_with_output_param(type *input_param, type *ptr_out)<br />
{<br />
krb5_error_code ret;<br />
type *ptr = NULL;<br />
<br />
*ptr_out = NULL;<br />
<br />
stuff that can go wrong here, allocating ptr;<br />
<br />
*ptr_out = ptr;<br />
ptr = NULL;<br />
<br />
cleanup:<br />
free_function(ptr);<br />
other cleanup code here;<br />
return ret;<br />
}<br />
</pre><br />
<br />
Simple wrapper functions can delegate the initialization of output paremeters to the functions they wrap, ''unless'' they are invoking the wrapped function through a function pointer.<br />
<br />
=== Current conformance ===<br />
<br />
Existing code mostly does not conform. Filling in caller-allocated structures is common (though far from universal) in the public libkrb5 API.<br />
<br />
=== Rationale ===<br />
<br />
Naming output parameters with an "_out" suffix helps readers easily identify them, and also makes it clearer when a resource's ownership is transferred to the caller. Since output parameters are only used near the beginning and end of a function, the extra verbosity is not very burdensome.<br />
<br />
Initializing output parameters makes it clear to static analysis tools that the previous value of the output parameter will not be used. If there happens to be a bug in the function such that it returns success but does not set output parameters, or in the caller such that it uses an output parameter even though the function returned failure, then the bug will result in predictable behavior (generally a NULL pointer dereference) with no security consequences beyond a denial of service attack.<br />
<br />
== Assignments as truth values ==<br />
<br />
Do not use assignments as truth values. Rather than this:<br />
<br />
<pre><br />
/* bad style */<br />
if ((ret = krb5_foo()))<br />
/* ... */;<br />
</pre><br />
<br />
do this:<br />
<br />
<pre><br />
/* better style */<br />
ret = krb5_foo();<br />
if (ret)<br />
/* ... */;<br />
</pre><br />
<br />
=== Current conformance ===<br />
<br />
Existing code varies widely.<br />
<br />
=== Rationale ===<br />
<br />
This makes the code easier to read, and also makes it easier to use<br />
debuggers. It may be excusable to put assignments into the<br />
conditional espression of a "while" statement, though, like:<br />
<br />
<pre><br />
while ((ch = getopt(argc, argv, "abn")) != -1)<br />
/* ... */;<br />
</pre><br />
<br />
Using assignments as truth values in conditional expressions ("ternary expressions") may make<br />
code particularly impenetrable.<br />
<br />
== The many names of zero ==<br />
<br />
There are at least three types of "zero" known to C. These are the<br />
integer zero (0), the null pointer constant (NULL), and the character<br />
constant zero ('\0'). Yes, these are usually all technically the<br />
integer zero. Use them in their correct contexts. (Purists will<br />
point out that 0 is a valid null pointer constant; still, do not use 0<br />
to specify a null pointer constant. For further unconfusion, read the<br />
section on null pointer constants in the comp.lang.c FAQ.) Do not use a lone<br />
variable as a truth value unless it's of integer type. Thus:<br />
<br />
<pre><br />
int i;<br />
char *cp;<br />
/* ... */<br />
if (i)<br />
/* ... */;<br />
if (cp != NULL) {<br />
while (*cp != '\0')<br />
/* ... */;<br />
}<br />
</pre><br />
<br />
Do not cast uses of NULL unless you're calling a function with a<br />
variable number of arguments, in which case you should cast it to to<br />
the appropriate pointer type. (NULL may be defined as 0, and an integer 0<br />
may not be the same size in the argument list as a pointer on a 64-bit<br />
platform.) Likewise, do not cast the return value<br />
from malloc() and friends; the prototype should declare them properly<br />
as returning a void&nbsp;* and thus shouldn't require an explicit cast.<br />
<br />
In any case, reading the section in the C FAQ on null pointers is<br />
highly recommended to remove confusion regarding null pointers in C,<br />
since this is a subject of much confusion to even experienced<br />
programmers. In particular, if you do not understand why using<br />
calloc() to allocate a struct that contains pointer members or why<br />
calling memset() to initialize such a struct to all-bytes-zero is<br />
wrong, reread that section again. Due to the prevalence of this practice and the practical difficulties of eliminating it, our [[portability assumptions]] currently require that platforms represent null pointers as all-bits-zero.<br />
<br />
== Brace placement ==<br />
<br />
Control flow statements that have a single statement as their body<br />
should nevertheless have braces around their bodies if the body is<br />
more than one line long, especially in the case of stacked multiple<br />
if-else clauses; use:<br />
<br />
<pre><br />
if (x) {<br />
if (y)<br />
foo();<br />
else<br />
bar();<br />
}<br />
</pre><br />
<br />
instead of:<br />
<br />
<pre><br />
/* bad style */<br />
if (x)<br />
if (y)<br />
foo();<br />
else<br />
bar();<br />
</pre><br />
<br />
which, while legible to the compiler, may confuse human readers and<br />
make the code less maintainable, especially if new branches get added<br />
to any of the clauses.<br />
<br />
If you are writing a do-while loop that has only one statement in its<br />
body, put braces around it anyway, since the while clause may be<br />
mistaken for a while loop with an empty body. Don't do this:<br />
<br />
<pre><br />
/* bad style */<br />
do<br />
foo();<br />
while (x);<br />
</pre><br />
<br />
Instead, write this:<br />
<br />
<pre><br />
/* better style */<br />
do {<br />
foo();<br />
} while (x);<br />
</pre><br />
<br />
== Preprocessor conditionals ==<br />
<br />
Instead of scattering <code>#ifdef</code> or other preprocessor conditionals throughout the code use preprocessor conditionals to control the definition of a function-like macro, or similar construct, which is used instead of embedded preprocessor conditionals in code.<br />
<br />
Instead of this:<br />
<br />
<pre><br />
do_something();<br />
/* bad style */<br />
#ifdef DEBUG<br />
fprintf(stderr, "did something\n");<br />
#endif<br />
do_something_else();<br />
</pre><br />
<br />
do something more like this:<br />
<br />
<pre><br />
#ifdef DEBUG<br />
#define DPRINTF(x) fprintf(stderr, x)<br />
#else<br />
#define DPRINTF(x) /* empty */<br />
#endif<br />
<br />
/* ... */<br />
<br />
do_something();<br />
/* better style */<br />
DPRINTF(("did something\n"));<br />
do_something_else();<br />
</pre><br />
<br />
Do not intersperse conditional compilation<br />
directives with control flow statements, as some combination of<br />
<code>#define</code>d symbols may result in statements getting eaten by dangling<br />
bits of control flow statements. When it is not possible to avoid<br />
this questionable practice (you really should rewrite the relevant<br />
code section), make use of redundant braces to make a compiler<br />
error more likely than incorrect runtime behavior (such as<br />
inadvertently providing someone with a root shell -- this has actually happened, long ago).<br />
<br />
Do not intersperse conditional compilation directives with control<br />
flow statements in such a way that confuses emacs cc-mode. Not only<br />
does emacs get confused, but the code becomes more difficult to read<br />
and maintain. Therefore, avoid code like this:<br />
<br />
<pre><br />
/* bad style */<br />
if (x) {<br />
f();<br />
}<br />
#ifdef FOO<br />
else if (y) {<br />
#else<br />
else {<br />
#endif<br />
g();<br />
}<br />
</pre><br />
<br />
Put comments after conditional compilation directives such as "#else"<br />
and "#endif". Make them correspond to the sense of the value that<br />
controls the compilation of the section they are closing, i.e.<br />
<br />
<pre><br />
#ifdef FOO<br />
/* ... */<br />
#else /* !FOO */<br />
/* ... */<br />
#endif /* !FOO */<br />
</pre><br />
<br />
Also, in the case of more complex conditional compilation directives,<br />
write the comments like this:<br />
<br />
<pre><br />
#if defined(FOO) || defined(BAR)<br />
/* ... */<br />
#else /* !(defined(FOO) || defined(BAR)) */<br />
/* ... */<br />
#endif /* !(defined(FOO) || defined(BAR)) */<br />
</pre><br />
<br />
=== Conformance ===<br />
<br />
Existing code mostly does not conform.<br />
<br />
=== Rationale ===<br />
<br />
Instances of "ifdef soup" make code more difficult to read, and make it more difficult to recognize bugs. It also interferes with automated reformatting and analysis tools.<br />
<br />
== Local variables ==<br />
<br />
Do not declare variables in an inner scope, e.g. inside the compound<br />
substatement of an if statement, unless the complexity of the code<br />
really demands that the variables be declared that way. In such<br />
situations, the function could probably stand to be broken up into<br />
smaller chunks anyway. Do not declare variables in an inner scope<br />
that shadow ones in an outer scope, since this leads to confusion.<br />
Also, some debugging environments, such as gdb under Solaris, can't<br />
see variables declared in an inner scope, so declaring such variables<br />
will make maintenance more difficult as well.<br />
<br />
== Placement of parentheses ==<br />
<br />
Parenthesize expressions that may be confusing, particularly where C's<br />
precedences are broken. For example, the shift operators have lower<br />
precedence than the +, -, *, /, and % operators. Perhaps the most<br />
familiar C precedence quirk is that equality and relational operators<br />
are of higher precedence than assignment operators. Less well known<br />
is that the bitwise operators are of a lower precedence than equality<br />
and relational operators.<br />
<br />
The sizeof operator takes either a unary expression or a parenthesized<br />
type name. It is not necessary to parenthesize the operand of sizeof<br />
if it is applied to a unary expression, but still, always parenthesize<br />
the operand of the sizeof operator. The sizeof operator does not<br />
evaluate its operand if it is a unary expression, so usages such as<br />
<br />
<pre><br />
s = sizeof(++foo);<br />
</pre><br />
<br />
should be avoided for the sake of sanity and readability.<br />
<br />
== Function-like macros ==<br />
<br />
Macros should have all-uppercase names. If it is necessary to use<br />
multiple statements, use braces, and wrap the whole thing in a<br />
do-while(0) construct, such as<br />
<br />
<pre><br />
#define FOOMACRO(x, y) do { \<br />
foo = (x) + (y); \<br />
f(y); \<br />
} while (0)<br />
</pre><br />
<br />
Leave off the semicolon at the end of a function-like macro, so that<br />
it can be mostly used like a call to a function without a return<br />
value. Line up the backslashes to make it more readable. Use M-x<br />
c-backslash-region in emacs to do neat lined-up backslashes.<br />
Parenthesize uses of arguments in the replacement text of a macro in<br />
order to prevent weird interactions.<br />
<br />
== Namespaces ==<br />
<br />
The C standard reserves a bunch of namespaces for the implementation.<br />
Don't stomp on them. For practical purposes, any identifier with a<br />
leading underscore should not be used. (Technically, ^_[a-z].* are<br />
reserved only for file scope, so should be safe for things smaller<br />
than file scope, but it's better to be paranoid in this case.)<br />
<br />
POSIX reserves typedef names ending with _t as well.<br />
<br />
Recall that errno is a reserved identifier, and is permitted to be a<br />
macro. Therefore, do not use errno as the name of a structure member,<br />
etc.<br />
<br />
Reserved namespaces are somewhat more restricted than this; read the<br />
appropriate section of the C standard if you have questions.<br />
<br />
If you're writing new library code, pick a short prefix and stick with<br />
it for any identifier with external linkage. If for some reason a<br />
library needs to have external symbols that should not be visible to<br />
the application, pick another (related) prefix to use for the internal<br />
globals. This applies to typedef names, tag names, and preprocessor<br />
identifiers as well.<br />
<br />
For the krb5 library, the prefix for public global symbols is "krb5_".<br />
Use "k5_" as a prefix for library internal globals. Avoid using "__"<br />
in symbol names, as it may confuse C++ implementations. There are<br />
admittedly a number of places where we leak thing into the namespace;<br />
we should try to fix these.<br />
<br />
Header files should also not leak symbols. Usually using the upcased<br />
version of the prefix you've picked will suffice, e.g. "KRB5_" as a<br />
CPP symbol prefix corresponding to "krb5_". In general, do not define<br />
macros that are lowercase, in order to avoid confusion and to prevent<br />
namespace collisions.<br />
<br />
Do not formulaically apply prefixes such as krb5_ or krb5int_ to static<br />
function names. It is better for static functions to have short<br />
descriptive, and it can be confusing to see the krb5_ prefix on a symbol<br />
which is not actually part of the krb5 API.<br />
<br />
The C standard only guarantees six case-insensitive characters to be<br />
significant in external identifiers; this is largely regarded as<br />
obsolescent even in 1989 and we will ignore it. It does, however,<br />
only guarantee 31 case-sensitive characters to be signficant in<br />
internal identifiers, so do not use identifiers that differ beyond the<br />
31st character. This is unlikely to be a problem, though.<br />
<br />
== Function length ==<br />
<br />
Functions should not be longer than about 60 lines. Strongly consider breaking up functions that are longer than this limit.<br />
<br />
=== Conformance ===<br />
<br />
Existing code conforms somewhat, with some egregious exceptions. Some functions exceed 500 lines in length. Older internal library symbols use "krb5int_" as a prefix instead of "k5_".<br />
<br />
=== Rationale ===<br />
<br />
Functions that are excessively lengthy are difficult to read. Especially when the beginning of a control structure does not fit on the same screen or page as its end, maintenance can become problematic. 60 lines is about the maximum length that can comfortably fit on a sheet of letter-sized paper.<br />
<br />
== Nesting depth ==<br />
<br />
The maximum indentation level should not be more than four. Deeply nested control flow generally indicates that a function needs to be broken into smaller pieces.<br />
<br />
=== Conformance ===<br />
<br />
Existing code conforms somewhat.<br />
<br />
=== Rationale ===<br />
<br />
Deeply nested control flow is difficult to read.<br />
<br />
== Copyright/License Statements ==<br />
<br />
Each applicable copyright/license statement for a file should appear by itself in a block comment. Copyright/license statements should appear near the top of source files, after any emacs formatting or filename comments but before any descriptive comments or non-comment lines of source code. See prototype/prototype.c and prototype/prototype.h for a more detailed example.<br />
<br />
All unique (except for year) copyright/license statements should appear in the top-level NOTICE file.<br />
<br />
=== Conformance ===<br />
<br />
Existing code mostly conforms, except that copyright/license statements do not usually appear by themselves in block comments. In a few cases copyright/license statements appear later on in source files and should be moved to the top.<br />
<br />
=== Rationale ===<br />
<br />
Formatting license comments this way allows them to be extracted from source code by scripts, without the need for ugly markers. The top-level NOTICE file makes it easier to satisfy the documentation requirements of licenses and to determine all of the terms under which MIT Kerberos may be used.<br />
<br />
== C99 features ==<br />
<br />
Use static inline functions instead of macros where possible. Variadic macros may be used when needed.<br />
<br />
Where fixed-width integer types are required, use types from <stdint.h> such as int32_t. Where an integer type of at least 64 bits is required, use "long long".<br />
<br />
Do not use designated initializers or compound literals in code which is built on Windows. They may be used in code which is not built on Windows.<br />
<br />
Avoid using declarations after statements (see [[#Local Variables | Local Variables]]). Absolutely do not use them in code which is built on Windows.<br />
<br />
Do not use variable-length arrays or alloca().<br />
<br />
Do not use // comments (see [[Coding_style/Formatting#Comment Formatting | Comment Formatting]]).<br />
<br />
=== Conformance ===<br />
<br />
Older code uses Kerberos-specific fixed-width integer types such as krb5_int32. Types from <stdint.h> can be used interchangeably with these types while we migrate away from them.<br />
<br />
=== Rationale ===<br />
<br />
At this time, official builds of Kerberos for Windows are performed using Visual Studio 2010, which supports only a subset of C99 features (see [[Portability research]]). Support for the inline keyword is ensured by <win-mac.h>.<br />
<br />
Variable-length arrays are unsafe because there is no error checking. If the length can be controlled by an attacker, security-critical bugs may result.<br />
<br />
== Misc. to be sorted ==<br />
<br />
Assume, for most purposes, working ANSI/ISO C ('89, not '99) support,<br />
both for internal use and for applications compiling against Kerberos<br />
header files and libraries. Some exceptions are noted below.<br />
<br />
When calling a function through a variable which holds a function<br />
pointer, explicitly deference the variable in order to make it easy<br />
to see that the call is through a function pointer. Do not explicitly<br />
dereference the pointer if it is contained within a structure or union,<br />
since there is no ambiguity in that case. Do not explicitly take the<br />
address of a function in order to assign it to a function pointer.<br />
Thus:<br />
<br />
<pre><br />
int (*fp)(void);<br />
int foofunc(void);<br />
fp = foofunc;<br />
x = (*fp)();<br />
x = vtable.funcname();<br />
x = vtable->funcname();<br />
</pre><br />
<br />
In general, do not take the address of an array. It does not return a<br />
pointer to the first element; it returns a pointer to the array<br />
itself. These are often identical when cast to an integral type, but<br />
they are inherently of different types themselves. Functions that<br />
take array types or pointers to array types as arguments can be<br />
particularly trouble-prone.<br />
<br />
If a function is declared to return a value, do not call "return"<br />
without an argument or allow the flow of control to fall off the end<br />
of the function.<br />
<br />
Always declare the return type of a function, even if it returns int.<br />
Yes, this means declaring main() to return int, since main() is<br />
required to return int by the standard. If a function is not supposed<br />
to return a value, declare it as returning void rather than omitting<br />
the return type, which will default the return type to int.<br />
<br />
Use ANSI C prototype-style function declarations and definitions. For functions with no parameters, use "(void)" in both the declaration and definition.<br />
<br />
Don't pass or return structures in API functions except by address.<br />
<br />
Every function should have a block comment describing briefly in complete sentences what it does, what inputs and outputs it has, and what error codes it can return. It should also describe any unusual aspects of the function. If the function is prototyped in a header file, the block comment should precede the prototype in the header file; otherwise it should precede the function definition.<br />
<br />
Strive to make your code capable of compiling using "gcc -Wall<br />
-Wmissing-prototypes -Wtraditional -Wcast-align<br />
-pedantic" [XXX need to rethink this<br />
somewhat] without generating any errors or warnings. Do not, however,<br />
compile using the "-ansi" flag to gcc, since that can result in odd<br />
behavior with header files on some systems, causing some necessary<br />
symbols to not be defined.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6038Release engineering notes2023-07-06T18:44:09Z<p>Ghudson: /* Pulling up changes to release branches */</p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork and waiting for Github Actions to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y".<br />
* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>. Commit with the subject "Update config.guess, config.sub"<br />
* On the master branch, run "make regen". Commit with the subject "make regen". Push the master branch to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Update any notes about transitions (such as enctype deprecations) and add new ones if necessary.<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1), and update the list of contributors and any changes to transitional notes from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make regen</code> and commit if there is more than just a pot file date change, with the commit message "make regen"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>make regen</code> with updated patchlevel.h<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6037Release engineering notes2023-04-17T14:26:29Z<p>Ghudson: </p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y".<br />
* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>. Commit with the subject "Update config.guess, config.sub"<br />
* On the master branch, run "make regen". Commit with the subject "make regen". Push the master branch to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Update any notes about transitions (such as enctype deprecations) and add new ones if necessary.<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1), and update the list of contributors and any changes to transitional notes from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make regen</code> and commit if there is more than just a pot file date change, with the commit message "make regen"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>make regen</code> with updated patchlevel.h<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6036Release engineering notes2023-04-13T22:48:26Z<p>Ghudson: /* Creating a new release branch */</p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y".<br />
* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>. Commit with the subject "Update config.guess, config.sub"<br />
* On the master branch, run "make regen". Commit with the subject "make regen". Push the master branch to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Update any notes about transitions (such as enctype deprecations) and add new ones if necessary.<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1), and update the list of contributors and any changes to transitional notes from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6035Release engineering notes2023-04-13T21:47:23Z<p>Ghudson: /* Creating a new release branch */</p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y".<br />
* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>. Commit with the subject "Update config.guess, config.sub"<br />
* On the master branch, run "make regen". Commit with the subject "make regen". Push the master branch to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Update any notes about transitions (such as enctype deprecations) and add new ones if necessary.<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1).<br />
** In README, copy the list of contributors from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6034Release engineering notes2023-04-13T21:25:49Z<p>Ghudson: /* Creating a new release branch */</p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y".<br />
* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>. Commit with the subject "Update config.guess, config.sub"<br />
* On the master branch, run "make regen". Commit with the subject "make regen". Push the master branch to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1).<br />
** In README, copy the list of contributors from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6033Release engineering notes2023-04-13T21:14:23Z<p>Ghudson: /* Creating a new release branch */</p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y" and push to the authoritative repository.<br />
* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>. Commit with the subject "Update config.guess, config.sub" and push to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1).<br />
** In README, copy the list of contributors from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Committer_resources&diff=6032Committer resources2022-04-13T18:17:58Z<p>Ghudson: </p>
<hr />
<div>This is information for developers who are [[Committers|committers]] to our repository.<br />
<br />
== Enrollment ==<br />
<br />
* Athena account: MITKC staff will sponsor as appropriate. See http://web.mit.edu/accounts/www/getaccount.html for some overview information about Athena accounts.<br />
* X.509 client certificate: Needed for RT access, among others. Information on how to obtain one is at http://web.mit.edu/ist/topics/certificates/index.html<br />
* RT account<br />
* Git access<br />
* Posting authorization to cvs-krb5 if you are going to commit stuff.<br />
* Coverity scan access<br />
<br />
== Where stuff is at ==<br />
<br />
* Git URL: krbdev.mit.edu:/git/krb5.git -- you may need to put "username@" in front if your local username is not the same as your Athena account name. Clone this instead of git@github.com:krb5/krb5.git when setting up your local repository in order to be able to push changes.<br />
* SSH to athena.dialup.mit.edu if you want easy access to AFS, a UNIX shell, etc.<br />
** You'll need to set GSSAPIDelegateCredentials=yes in order to do passwordless login, because user home directories are in AFS, and the administrators didn't want to confuse users who logged in with Kerberos but couldn't access their files.<br />
* RT https://krbdev.mit.edu/rt/ (or https://krbdev.mit.edu:444/rt/ if your browser doesn't deal with "optional" SSL client certificate verification)<br />
<br />
== Accessing krbdev.mit.edu ==<br />
<br />
The preferred way to access krbdev.mit.edu is with GSSAPI krb5 authentication. It is not necessary to delegate credentials. publickey authentication can be set up if required.<br />
<br />
== RT headers ==<br />
<br />
If a commit makes a user-visible change, such as adding a new feature or fixing a user-visible bug in a previous release, it should be associated with an RT ticket. Do this by adding RT pseudo-headers at the end of the commit message, after a blank line. The most important header is "ticket:", which associates the commit with a ticket number. Add "tags: pullup" and "target_version: X.Y-next" if the commit should be pulled up to a release branch. Here is an example:<br />
<br />
Use correct profile var in krb5_get_tgs_ktypes<br />
<br />
In r21879, when we converted to using KRB5_CONF macros for profile<br />
variable names, we made a typo in krb5_get_tgs_ktypes and erroneously<br />
started using default_tkt_enctypes instead of default_tgs_enctypes for<br />
TGS requests. Fix the typo and return to the documented behavior.<br />
<br />
ticket: 7155<br />
target_version: 1.10-next<br />
tags: pullup<br />
<br />
A ticket can multiple target_version values. If a fix needs to go into multiple releases, use a separate target_version header for each one.<br />
<br />
=== New tickets ===<br />
<br />
If you are creating a new ticket, run "ssh krbdev.mit.edu krb5-rt-id" to reserve a ticket number, and put "ticket: NNNN (new)" in the commit message, substituting the ticket number for NNNN. The summary line of the commit will be used as the subject of the new ticket; if this is not what you want, you can use a "subject:" RT header to set the ticket subject, or you can change the subject afterwards in RT.<br />
<br />
You can automate this process using a [https://raw.github.com/krb5/krbdev-services/master/githooks-client/commit-msg commit-msg hook]. Drop the contents of the hook into .git/hooks/commit-msg and make it executable. Then you can put just "ticket: new" at the end of a commit message, and the hook will automatically reserve a ticket number and rewrite the header to "ticket: NNNN (new)". You should have some form of passwordless login to krbdev.mit.edu set up for this to work transparently.<br />
<br />
=== More about RT keywords ===<br />
<br />
These are somewhat inconsistent and will need more editing:<br />
* Additional detail about [[RT keywords]]<br />
* [[Manipulating RT tickets using commits]]<br />
<br />
== Pushing changes from contributors ==<br />
<br />
When integrating code changes created by contributors, take note of the following:<br />
<br />
* If the change is presented to you as one or more git commits, fetch the commit into your local git repository and then use git cherry-pick to make a copy of the relevant commits onto your master branch (or a topic branch). Do not use git merge.<br />
<br />
* If the change is presented to you as a patch, make a commit from the patch and use the --author flag to git commit to set the commit author field to the author's name and email address.<br />
<br />
* Review the changes as well as possible, and make sure they are organized into logical commits as required by our [[Coding_style/Version_control_practices|version control practices]]. Run the C style checker to identify possible style issues.<br />
<br />
* Make sure the changes build and pass "make check".<br />
<br />
* Add appropriate RT headers to the commit messages if appropriate.<br />
<br />
* If you need to make significant changes to the commit or commit message, you can add a note to the end (before any RT headers) like:<br />
<br />
[ghudson@mit.edu: Stylistic changes, commit message]</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6031RT server configuration2022-04-13T17:13:51Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
The server hosts the authoritative git repository, so the git package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
git<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
<br />
Some of the above accounts may be created by ops during provisioning. /var/rt2 and /var/rt2/.ssh must be owned by rtcvs or sshd will reject logins as rtcvs.<br />
<br />
For the authoritative repository, create a group named "krbwrite" and an account for each committer, with a root-owned home directory and git-shell configuration:<br />
<br />
groupadd krbwrite<br />
# Repeat the following commands for each committer.<br />
useradd -u 3622 -s /usr/bin/git-shell -G krbwrite ghudson<br />
mkdir /home/ghudson<br />
mkdir /home/ghudson/git-shell-commands<br />
ln -s /git/krb5.git/hooks/krb5-rt-id /home/ghudson/git-shell-commands<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from hooks/krbsnap_rsa_key.pub in the authoritative repository.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* The authoritative krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* The authoritative krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
ticket: new<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rtcvs, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.<br />
<br />
==Git repository==<br />
<br />
The authoritative krb5 git repository lives in /git/krb5.git. If this repository needs to be reconstructed from another mirror of the repository, install the hooks from the githooks directory of krbdev-services, add the krbsnap private and public SSH key to the hooks directory, and run the git configuration commands from gitconvert/krb5-convert.sh in krbdev-services.<br />
<br />
The authoritative krbdev-services repository lives in /git/krbdev-services.git.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6030RT server configuration2022-04-13T06:01:07Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
The server hosts the authoritative git repository, so the git package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
git<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
<br />
Some of the above accounts may be created by ops during provisioning. /var/rt2 and /var/rt2/.ssh must be owned by rtcvs or sshd will reject logins as rtcvs.<br />
<br />
For the authoritative repository, create a group named "krbwrite" and an account for each committer, with a root-owned home directory and git-shell configuration:<br />
<br />
groupadd krbwrite<br />
# Repeat the following commands for each committer.<br />
useradd -u 3622 -s /usr/bin/git-shell -G krbwrite ghudson<br />
mkdir /home/ghudson<br />
mkdir /home/ghudson/git-shell-commands<br />
ln -s /git/krb5.git/hooks/krb5-rt-id /home/ghudson/git-shell-commands<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from hooks/krbsnap_rsa_key.pub in the authoritative repository.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* The authoritative krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* The authoritative krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
ticket: new<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rtcvs, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.<br />
<br />
==Git repository==<br />
<br />
The authoritative git repository lives in /git/krb5.git. If this repository needs to be reconstructed from another mirror of the repository, install the hooks from the githooks directory of krbdev-services, add the krbsnap private and public SSH key to the hooks directory, and run the git configuration commands from gitconvert/krb5-convert.sh in krbdev-services.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6029RT server configuration2022-04-12T23:20:18Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
<br />
Some of the above accounts may be created by ops during provisioning. /var/rt2 and /var/rt2/.ssh must be owned by rtcvs or sshd will reject logins as rtcvs.<br />
<br />
For the authoritative repository, create a group named "krbwrite" and an account for each committer, with a root-owned home directory and git-shell configuration:<br />
<br />
groupadd krbwrite<br />
useradd -u 3622 -s /usr/bin/git-shell -G krbwrite ghudson<br />
mkdir /home/ghudson<br />
mkdir /home/ghudson/git-shell-commands<br />
ln -s /git/krb5.git/hooks/krb5-rt-id /home/ghudson/git-shell-commands<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from hooks/krbsnap_rsa_key.pub in the authoritative repository.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* The authoritative krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* The authoritative krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
ticket: new<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rtcvs, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6028RT server configuration2022-04-12T23:09:22Z<p>Ghudson: /* User accounts */</p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
<br />
Some of the above accounts may be created by ops during provisioning. /var/rt2 and /var/rt2/.ssh must be owned by rtcvs or sshd will reject logins as rtcvs from drugstore.<br />
<br />
For the authoritative repository, create a group named "krbwrite" and an account for each committer, with a root-owned home directory and git-shell configuration:<br />
<br />
groupadd krbwrite<br />
useradd -u 3622 -s /usr/bin/git-shell -G krbwrite ghudson<br />
mkdir /home/ghudson<br />
mkdir /home/ghudson/git-shell-commands<br />
ln -s /git/krb5.git/hooks/krb5-rt-id /home/ghudson/git-shell-commands<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from hooks/krbsnap_rsa_key.pub in the authoritative repository.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* The authoritative krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* The authoritative krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
ticket: new<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rtcvs, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Getting_source_code&diff=6027Getting source code2021-12-14T20:21:10Z<p>Ghudson: </p>
<hr />
<div>The MIT Kerberos source code is in a Git repository.<br />
<br />
== Official releases ==<br />
<br />
Typically, end users and system administrators who want the latest stable MIT krb5 software should use the official releases:<br />
<br />
* [http://web.mit.edu/kerberos/dist/ MIT Keberos download page]<br />
<br />
== Git repository access ==<br />
<br />
The current development source code is now in a Git repository. The latest development code is on the "master" branch, as is usual for Git. (It used to be "trunk" when the main repository was in Subversion.) Developers wishing to contribute changes to the krb5 software should track this repository. Advanced end users and system administrators may also wish to obtain the latest development sources from this repository.<br />
<br />
The krb5 repository migrated to Git during the weekend of 2012-05-11. Use the following URLs for read-only access.<br />
<br />
* git://github.com/krb5/krb5.git for the public read-only Git access<br />
* https://github.com/krb5/krb5 for browsing<br />
<br />
If you are interested in contributing changes to our repository, please consult our [[Coding style/Version control practices | version control practices]] page. You should of course test changes before submitting them for inclusion; see [[Building]] for the additional steps needed to build from a git checkout and [[Test suite]] for more information about the regression tests. Additional information about the [[Git migration]] is available, including help for situations where you have an existing GitHub fork of the krb5-anonsvn Git repository.<br />
<br />
There is a wiki page with details about the [[Git conversion]] process available for people who are interested in the technical details.<br />
<br />
== Repository browsing ==<br />
<br />
* https://github.com/krb5/krb5 for browsing on GitHub</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=TGS_Requests&diff=6026TGS Requests2021-12-09T07:19:31Z<p>Ghudson: /* References */</p>
<hr />
<div>Kerberos Ticket Granting Service (TGS) requests are one of the most complicated areas of processing in MIT krb5, in both the client and the KDC. Here are some notes on the different kind of TGS requests and what considerations must be made when processing them.<br />
<br />
==Protocol structure==<br />
<br />
Like an AS request, a TGS request contains a KDC-REQ-BODY sequence and a sequence of PA-DATA. One of the pa-data elements will have type PA-TGS-REQ; its value will contain an AP-REQ, the same protocol structure a client would use to authenticate to an application server. The ticket in the AP-REQ is called the "header ticket" within the MIT KDC source code, because {{rfcref|4120}} uses the term "authentication header" to refer to the AP-REQ.<br />
<br />
The authenticator in the AP-REQ contains a checksum over the encoding of the body. This checksum need not be keyed, as it is contained within an encrypted payload, but with modern encryption types it is usually a keyed checksum anyway. There is no intrinsic cryptographic binding between other padata elements and the PA-TGS-REQ or the body.<br />
<br />
The authenticator in the AP-REQ may contain a subkey, in which case the TGS response should be encrypted in the subkey. Otherwise it should be encrypted in the session key of the header ticket. There are four historical interoperability bugs affecting the use of subkeys in TGS requests, as described here:<br />
<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/DD8CFMuWiHJhkkoHGbjx0Z1dpKo<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/4qhYxn7iovCnfsHL8wmim7-8Tq0<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/hl6PvUz94IQMFadSybnjGYeBCCE<br />
<br />
TGS requests may use FAST implicit armor ({{rfcref|6113}} section 5.4). In this case one of the pa-data elements will have type PA-FX-FAST and its value will contain a second copy of the TGS request encrypted in a key derived from the subkey (which must be present) and the ticket session key.<br />
<br />
==Normal TGS requests==<br />
<br />
For the purposes of this article, a TGS request is considered "normal" if it:<br />
<br />
* does not have any of the forwarded, proxy, renew, validate, enc-tkt-in-skey, or cname-in-addl-tkt options<br />
* does not contain PA-FOR-USER or PA_S4U_X509_USER pa-data.<br />
<br />
The header ticket for a normal TGS request server have an sname field of krbtgt/THIS.REALM, where THIS.REALM must match the realm field of the TGS request. If the header ticket is a cross-realm TGT (the ticket's srealm field is some OTHER.REALM different from THIS.REALM), the ticket's crealm must also be different from THIS.REALM; this is called the "lineage check", and ensures that foreign realms cannot issue tickets for local users. The KDC also (unless requested not to) checks the transited list in the ticket to ensure that OTHER.REALM has the authority to issue tickets for the realm of the header ticket client, and adds OTHER.REALM to the transited list of the issued ticket if it does not match the realm of the header ticket client.<br />
<br />
If the requested server is a TGS principal for a different realm, the KDC may issue a ticket to an alternative TGS principal for an intermediate realm instead. If the requested server is not a TGS server but the request has the "canonicalize" KDC option set ({{rfcref|6803}} section 3), the KDC may issue a ticket to an outgoing TGS principal; this is called a "referral".<br />
<br />
For local clients, some KDC implementations look up the client DB entry and apply the entry's policy in case it has changed (e.g. the account has been revoked). The MIT krb5 KDC does not currently do this.<br />
<br />
It is possible for an otherwise normal TGS request to be part of a cross-realm Resource-Based Constrained Delegation (RBCD) operation transiting through this realm. In this case, the header ticket will be a cross-realm TGT, the request server will be a cross-realm TGS, the header ticket PAC will contain an S4U_DELEGATION_INFO buffer giving the ticket client as the last transited service, and the PAC_CLIENT_INFO buffer will contain a realm part in the name. These requests can be processed the same way as a normal TGS request, but when issuing a PAC for the resulting ticket the KDC must copy the PAC_CLIENT_INFO and S4U_DELEGATION_INFO buffers from the header ticket.<br />
<br />
==Ticket modification requests==<br />
<br />
A ticket modification request has the forwarded, proxy, renew, or validate option. The header ticket is not required to be a TGT, and must not be a TGT if the proxy option is requested. The request sname must match the ticket sname, and the KDC must not be issuing a referral. The header ticket must have a flag corresponding to the requested option (forwardable for forwarded, etc.) The issued ticket will be similar in most respects to the header ticket, except for the addresses, validity times, and invalid flag as indicated by the request option.<br />
<br />
==User-to-user requests==<br />
<br />
If the enc-tkt-in-skey option is requested, the request must contain a second ticket in the additional-tickets field. The second ticket must be a local-realm TGT for the server realm (krbtgt/THIS.REALM@THIS.REALM), and the second ticket cname and crealm must match the request sname and realm. The request is processed similarly to a normal request, but the resulting ticket will be encrypted in the session key of the second ticket, and will have a session key of the same type as the second ticket's. User-to-user requests cannot generate referrals.<br />
<br />
==S4U2Self (protocol transition) requests==<br />
<br />
If the request pa-data contains an element of type PA-FOR-USER or PA_S4U_X509_USER or both, it is a request to issue a ticket from a named user (known as the "subject") to the requesting service. The subject may be identified by principal or by X.509 certificate. S4U2Self requests do not require special privileges, although in some cases the forwardable flag will be cleared on the resulting ticket. S4U2Self requests must not contain any options for other kinds of special TGS requests (ticket modification, user-to-user, and S4U2Proxy).<br />
<br />
For a local-realm S4U2Self requests, the request server must match the header ticket client, although they may use different aliases for the same principal. A PAC must be present in the header ticket, although it is not used as a basis for the PAC in the issued ticket. The subject is looked up in the database, checked for policy constraints, and a PAC is issued for it as it would be for an AS request. Authentication indicators are not copied from the header ticket, as there was no actual authentication of the subject.<br />
<br />
For cross-realm S4U2Self scenarios, there are four different kinds of requests:<br />
<br />
1. Zero or more AS requests to determine the subject realm, if it is not already known. These may be ordinary AS requests, but they may also contain PA_S4U_X509_USER if the user is identified by a certificate. The requesting service begins at the service realm and follows the chain of KDC_ERR_WRONG_REALM errors until a KDC_ERR_PREAUTH_REQUIRED error is received or a ticket is issued, indicating that the subject realm is known. The requesting server then obtains a cross-realm TGT to the subject realm using ordinary TGS requests.<br />
<br />
2. A cross-realm S4U2Self request to the subject realm. Since the requesting service does not live in this realm, the request server will contain the representation of a requesting service as an enterprise principal. As for a local S4U2Self request, the subject realm KDC looks up the subject in the database, checks it for policy constraints, and constructs a PAC for the subject. Unlike a local request, the PAC_CLIENT_INFO name in the PAC will contain an "@REALM" suffix identifying the subject realm, and the KDC issues a referral TGT back towards the service realm. The reply includes PA_S4U_X509_USER naming the subject principal, in case a certificate was used to identify it.<br />
<br />
3. Zero or more cross-realm S4U2Self requests to intermediate realms along the path back to the service realm, each resulting in a referral TGT. The S4U2Self padata in these requests must contain the subject principal name; the subject can no longer be identified by certificate at this step. As in step 2, the PAC in the issued referral TGTs must be for the subject and must contain an "@REALM" suffix in the PAC_CLIENT_INFO name.<br />
<br />
4. A cross-realm S4U2Self request to the service realm. This type of request would ordinarily fail the lineage check (as the client is in the local realm and the TGT was issued by another realm), so S4U2Self requests are excepted from this check. The service realm KDC issues a ticket from the subject to the requesting service, using the PAC in the the referral ticket as a basis. However, the PAC_CLIENT_INFO name for the PAC does not contain the "@REALM" suffix.<br />
<br />
S4U2Self requests override the no_authdata_required flag on the requesting service principal. Although the service may not require authorization data for tickets received from clients, its use of S4U2Self strongly suggests the need for a PAC--either the service plans to make an S4U2Proxy request, or it has a special need to inspect the PAC for a subject.<br />
<br />
If the requesting service has any outgoing constrained delegation privileges, but does not have the ok_to_auth_as_delegate principal flag, then the forwardable ticket flag will be suppressed on tickets issued to it via S4U2Self. The intent is to prevent the use of S4U2Self-issued tickets as S4U2Proxy evidence tickets without this extra privilege when outgoing authorizations are used (but not when the delegation is allowed by an incoming authorization on the delegation target).<br />
<br />
==S4U2Proxy (constrained delegation) requests==<br />
<br />
If the cname-in-addl-tkt option is requested, the request is for a ticket from some client (known here as the "subject") to another service. The request must contain a second ticket (known as the "subject ticket" or "evidence ticket") in the additional-tickets field to identify the subject. The subject ticket must have the forwardable flag set. The request must not contain any options or padata for other kinds of special TGS requests (ticket modification, user-to-user, or S4U2Self). S4U2Proxy operations require special privileges, which may be modeled as outgoing delegation privileges on the requesting service or incoming delegation privileges on the delegation target. When incoming delegation privileges are used, the operation is known as resource-based constrained delegation (RBCD) and the delegation target may be in a different realm from the requesting service. Otherwise, the requesting service and delegation target must be in the same realm.<br />
<br />
There are three parties to an S4U2Proxy operation:<br />
<br />
1. The subject, which will be the cname and crealm of the resulting ticket. This party may also be known as the "client", although that term may be confused for the requesting service. For a local-realm S4U2Proxy or initial RBCD request, this is the client of the subject ticket. For a cross-realm RBCD request, the subject is identified by the PAC in the subject ticket.<br />
<br />
2. The requesting service, as give by the client of the header ticket. This may also be known as the impersonator.<br />
<br />
3. The delegation target, which will be the sname and realm of the resulting ticket. This party may also be known as the "resource", the "server" (because it is given by the sname and realm of the KDC request), the "proxy target", or (particularly in Microsoft documentation) just the "proxy". Experience has shown that the term "proxy" is easily confused with the impersonator, so the MIT implementation uses this term sparingly. The delegation target must not be a TGS name.<br />
<br />
A PAC must be present in both the header ticket and subject ticket. For a cross-realm RBCD request, the PAC must contain an S4U_DELEGATION_INFO buffer with the requesting service as the last transited_service and the delegation target as the proxy_target, and an "@REALM" suffix in the PAC_CLIENT_INFO name. For a local S4U2Proxy request, the PAC must be for the second ticket client. The PAC in the header ticket must be for the requesting service.<br />
<br />
For a local-realm or initial RBCD request, the KDC adds S4U_DELEGATION_INFO to the PAC in the issued service ticket or referral TGT. Any transited services specified in the subject PAC's delegation info (if it had one) are copied, and the requesting service is added to the end. The proxy_target field is set to the delegation target. Final RBCD requests verify and copy delegation info from the subject PAC without modifying it.<br />
<br />
==References==<br />
<br />
RFC 4120 specifies the base Kerberos 5 protocol.<br />
<br />
RFC 6113 specifies FAST.<br />
<br />
RFC 6803 specifies referrals.<br />
<br />
S4U2Self and S4U2Proxy are fully specified in [https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-sfu/3bff5864-8135-400e-bdd9-33b552051d94 [MS-SFU]].<br />
<br />
PACs are specified in [https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-pac/166d8064-c863-41e1-9c23-edaaa5f36962 [MS-PAC]].</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=TGS_Requests&diff=6025TGS Requests2021-12-09T07:15:40Z<p>Ghudson: </p>
<hr />
<div>Kerberos Ticket Granting Service (TGS) requests are one of the most complicated areas of processing in MIT krb5, in both the client and the KDC. Here are some notes on the different kind of TGS requests and what considerations must be made when processing them.<br />
<br />
==Protocol structure==<br />
<br />
Like an AS request, a TGS request contains a KDC-REQ-BODY sequence and a sequence of PA-DATA. One of the pa-data elements will have type PA-TGS-REQ; its value will contain an AP-REQ, the same protocol structure a client would use to authenticate to an application server. The ticket in the AP-REQ is called the "header ticket" within the MIT KDC source code, because {{rfcref|4120}} uses the term "authentication header" to refer to the AP-REQ.<br />
<br />
The authenticator in the AP-REQ contains a checksum over the encoding of the body. This checksum need not be keyed, as it is contained within an encrypted payload, but with modern encryption types it is usually a keyed checksum anyway. There is no intrinsic cryptographic binding between other padata elements and the PA-TGS-REQ or the body.<br />
<br />
The authenticator in the AP-REQ may contain a subkey, in which case the TGS response should be encrypted in the subkey. Otherwise it should be encrypted in the session key of the header ticket. There are four historical interoperability bugs affecting the use of subkeys in TGS requests, as described here:<br />
<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/DD8CFMuWiHJhkkoHGbjx0Z1dpKo<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/4qhYxn7iovCnfsHL8wmim7-8Tq0<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/hl6PvUz94IQMFadSybnjGYeBCCE<br />
<br />
TGS requests may use FAST implicit armor ({{rfcref|6113}} section 5.4). In this case one of the pa-data elements will have type PA-FX-FAST and its value will contain a second copy of the TGS request encrypted in a key derived from the subkey (which must be present) and the ticket session key.<br />
<br />
==Normal TGS requests==<br />
<br />
For the purposes of this article, a TGS request is considered "normal" if it:<br />
<br />
* does not have any of the forwarded, proxy, renew, validate, enc-tkt-in-skey, or cname-in-addl-tkt options<br />
* does not contain PA-FOR-USER or PA_S4U_X509_USER pa-data.<br />
<br />
The header ticket for a normal TGS request server have an sname field of krbtgt/THIS.REALM, where THIS.REALM must match the realm field of the TGS request. If the header ticket is a cross-realm TGT (the ticket's srealm field is some OTHER.REALM different from THIS.REALM), the ticket's crealm must also be different from THIS.REALM; this is called the "lineage check", and ensures that foreign realms cannot issue tickets for local users. The KDC also (unless requested not to) checks the transited list in the ticket to ensure that OTHER.REALM has the authority to issue tickets for the realm of the header ticket client, and adds OTHER.REALM to the transited list of the issued ticket if it does not match the realm of the header ticket client.<br />
<br />
If the requested server is a TGS principal for a different realm, the KDC may issue a ticket to an alternative TGS principal for an intermediate realm instead. If the requested server is not a TGS server but the request has the "canonicalize" KDC option set ({{rfcref|6803}} section 3), the KDC may issue a ticket to an outgoing TGS principal; this is called a "referral".<br />
<br />
For local clients, some KDC implementations look up the client DB entry and apply the entry's policy in case it has changed (e.g. the account has been revoked). The MIT krb5 KDC does not currently do this.<br />
<br />
It is possible for an otherwise normal TGS request to be part of a cross-realm Resource-Based Constrained Delegation (RBCD) operation transiting through this realm. In this case, the header ticket will be a cross-realm TGT, the request server will be a cross-realm TGS, the header ticket PAC will contain an S4U_DELEGATION_INFO buffer giving the ticket client as the last transited service, and the PAC_CLIENT_INFO buffer will contain a realm part in the name. These requests can be processed the same way as a normal TGS request, but when issuing a PAC for the resulting ticket the KDC must copy the PAC_CLIENT_INFO and S4U_DELEGATION_INFO buffers from the header ticket.<br />
<br />
==Ticket modification requests==<br />
<br />
A ticket modification request has the forwarded, proxy, renew, or validate option. The header ticket is not required to be a TGT, and must not be a TGT if the proxy option is requested. The request sname must match the ticket sname, and the KDC must not be issuing a referral. The header ticket must have a flag corresponding to the requested option (forwardable for forwarded, etc.) The issued ticket will be similar in most respects to the header ticket, except for the addresses, validity times, and invalid flag as indicated by the request option.<br />
<br />
==User-to-user requests==<br />
<br />
If the enc-tkt-in-skey option is requested, the request must contain a second ticket in the additional-tickets field. The second ticket must be a local-realm TGT for the server realm (krbtgt/THIS.REALM@THIS.REALM), and the second ticket cname and crealm must match the request sname and realm. The request is processed similarly to a normal request, but the resulting ticket will be encrypted in the session key of the second ticket, and will have a session key of the same type as the second ticket's. User-to-user requests cannot generate referrals.<br />
<br />
==S4U2Self (protocol transition) requests==<br />
<br />
If the request pa-data contains an element of type PA-FOR-USER or PA_S4U_X509_USER or both, it is a request to issue a ticket from a named user (known as the "subject") to the requesting service. The subject may be identified by principal or by X.509 certificate. S4U2Self requests do not require special privileges, although in some cases the forwardable flag will be cleared on the resulting ticket. S4U2Self requests must not contain any options for other kinds of special TGS requests (ticket modification, user-to-user, and S4U2Proxy).<br />
<br />
For a local-realm S4U2Self requests, the request server must match the header ticket client, although they may use different aliases for the same principal. A PAC must be present in the header ticket, although it is not used as a basis for the PAC in the issued ticket. The subject is looked up in the database, checked for policy constraints, and a PAC is issued for it as it would be for an AS request. Authentication indicators are not copied from the header ticket, as there was no actual authentication of the subject.<br />
<br />
For cross-realm S4U2Self scenarios, there are four different kinds of requests:<br />
<br />
1. Zero or more AS requests to determine the subject realm, if it is not already known. These may be ordinary AS requests, but they may also contain PA_S4U_X509_USER if the user is identified by a certificate. The requesting service begins at the service realm and follows the chain of KDC_ERR_WRONG_REALM errors until a KDC_ERR_PREAUTH_REQUIRED error is received or a ticket is issued, indicating that the subject realm is known. The requesting server then obtains a cross-realm TGT to the subject realm using ordinary TGS requests.<br />
<br />
2. A cross-realm S4U2Self request to the subject realm. Since the requesting service does not live in this realm, the request server will contain the representation of a requesting service as an enterprise principal. As for a local S4U2Self request, the subject realm KDC looks up the subject in the database, checks it for policy constraints, and constructs a PAC for the subject. Unlike a local request, the PAC_CLIENT_INFO name in the PAC will contain an "@REALM" suffix identifying the subject realm, and the KDC issues a referral TGT back towards the service realm. The reply includes PA_S4U_X509_USER naming the subject principal, in case a certificate was used to identify it.<br />
<br />
3. Zero or more cross-realm S4U2Self requests to intermediate realms along the path back to the service realm, each resulting in a referral TGT. The S4U2Self padata in these requests must contain the subject principal name; the subject can no longer be identified by certificate at this step. As in step 2, the PAC in the issued referral TGTs must be for the subject and must contain an "@REALM" suffix in the PAC_CLIENT_INFO name.<br />
<br />
4. A cross-realm S4U2Self request to the service realm. This type of request would ordinarily fail the lineage check (as the client is in the local realm and the TGT was issued by another realm), so S4U2Self requests are excepted from this check. The service realm KDC issues a ticket from the subject to the requesting service, using the PAC in the the referral ticket as a basis. However, the PAC_CLIENT_INFO name for the PAC does not contain the "@REALM" suffix.<br />
<br />
S4U2Self requests override the no_authdata_required flag on the requesting service principal. Although the service may not require authorization data for tickets received from clients, its use of S4U2Self strongly suggests the need for a PAC--either the service plans to make an S4U2Proxy request, or it has a special need to inspect the PAC for a subject.<br />
<br />
If the requesting service has any outgoing constrained delegation privileges, but does not have the ok_to_auth_as_delegate principal flag, then the forwardable ticket flag will be suppressed on tickets issued to it via S4U2Self. The intent is to prevent the use of S4U2Self-issued tickets as S4U2Proxy evidence tickets without this extra privilege when outgoing authorizations are used (but not when the delegation is allowed by an incoming authorization on the delegation target).<br />
<br />
==S4U2Proxy (constrained delegation) requests==<br />
<br />
If the cname-in-addl-tkt option is requested, the request is for a ticket from some client (known here as the "subject") to another service. The request must contain a second ticket (known as the "subject ticket" or "evidence ticket") in the additional-tickets field to identify the subject. The subject ticket must have the forwardable flag set. The request must not contain any options or padata for other kinds of special TGS requests (ticket modification, user-to-user, or S4U2Self). S4U2Proxy operations require special privileges, which may be modeled as outgoing delegation privileges on the requesting service or incoming delegation privileges on the delegation target. When incoming delegation privileges are used, the operation is known as resource-based constrained delegation (RBCD) and the delegation target may be in a different realm from the requesting service. Otherwise, the requesting service and delegation target must be in the same realm.<br />
<br />
There are three parties to an S4U2Proxy operation:<br />
<br />
1. The subject, which will be the cname and crealm of the resulting ticket. This party may also be known as the "client", although that term may be confused for the requesting service. For a local-realm S4U2Proxy or initial RBCD request, this is the client of the subject ticket. For a cross-realm RBCD request, the subject is identified by the PAC in the subject ticket.<br />
<br />
2. The requesting service, as give by the client of the header ticket. This may also be known as the impersonator.<br />
<br />
3. The delegation target, which will be the sname and realm of the resulting ticket. This party may also be known as the "resource", the "server" (because it is given by the sname and realm of the KDC request), the "proxy target", or (particularly in Microsoft documentation) just the "proxy". Experience has shown that the term "proxy" is easily confused with the impersonator, so the MIT implementation uses this term sparingly. The delegation target must not be a TGS name.<br />
<br />
A PAC must be present in both the header ticket and subject ticket. For a cross-realm RBCD request, the PAC must contain an S4U_DELEGATION_INFO buffer with the requesting service as the last transited_service and the delegation target as the proxy_target, and an "@REALM" suffix in the PAC_CLIENT_INFO name. For a local S4U2Proxy request, the PAC must be for the second ticket client. The PAC in the header ticket must be for the requesting service.<br />
<br />
For a local-realm or initial RBCD request, the KDC adds S4U_DELEGATION_INFO to the PAC in the issued service ticket or referral TGT. Any transited services specified in the subject PAC's delegation info (if it had one) are copied, and the requesting service is added to the end. The proxy_target field is set to the delegation target. Final RBCD requests verify and copy delegation info from the subject PAC without modifying it.<br />
<br />
==References==<br />
<br />
S4U2Self and S4U2Proxy are fully specified in [https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-sfu/3bff5864-8135-400e-bdd9-33b552051d94 [MS-SFU]].<br />
<br />
PACs are specified in [https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-pac/166d8064-c863-41e1-9c23-edaaa5f36962 [MS-PAC]].</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=TGS_Requests&diff=6024TGS Requests2021-12-09T06:36:03Z<p>Ghudson: </p>
<hr />
<div>Kerberos Ticket Granting Service (TGS) requests are one of the most complicated areas of processing in MIT krb5, in both the client and the KDC. Here are some notes on the different kind of TGS requests and what considerations must be made when processing them.<br />
<br />
==Protocol structure==<br />
<br />
Like an AS request, a TGS request contains a KDC-REQ-BODY sequence and a sequence of PA-DATA. One of the pa-data elements will have type PA-TGS-REQ; its value will contain an AP-REQ, the same protocol structure a client would use to authenticate to an application server. The ticket in the AP-REQ is called the "header ticket" within the MIT KDC source code, because {{rfcref|4120}} uses the term "authentication header" to refer to the AP-REQ.<br />
<br />
The authenticator in the AP-REQ contains a checksum over the encoding of the body. This checksum need not be keyed, as it is contained within an encrypted payload, but with modern encryption types it is usually a keyed checksum anyway. There is no intrinsic cryptographic binding between other padata elements and the PA-TGS-REQ or the body.<br />
<br />
The authenticator in the AP-REQ may contain a subkey, in which case the TGS response should be encrypted in the subkey. Otherwise it should be encrypted in the session key of the header ticket. There are four historical interoperability bugs affecting the use of subkeys in TGS requests, as described here:<br />
<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/DD8CFMuWiHJhkkoHGbjx0Z1dpKo<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/4qhYxn7iovCnfsHL8wmim7-8Tq0<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/hl6PvUz94IQMFadSybnjGYeBCCE<br />
<br />
TGS requests may use FAST implicit armor ({{rfcref|6113}} section 5.4). In this case one of the pa-data elements will have type PA-FX-FAST and its value will contain a second copy of the TGS request encrypted in a key derived from the subkey (which must be present) and the ticket session key.<br />
<br />
==Types of TGS requests==<br />
<br />
* Normal<br />
<br />
* Ticket modification<br />
<br />
* User-to-user<br />
<br />
* S4U2Self (aka "protocol transition")<br />
<br />
* S4U2Proxy (aka "constrained delegation"): if the CNAME-IN-ADDL-TICKET option is requested, the request body must contain an additional ticket (called the "evidence ticket") from a user to the requesting service--or, for a cross-realm request, a cross-TGT containing a PAC or equivalent authorization data for a user. If delegation is allowed to the requested server, the KDC issues a ticket from the evidence ticket client (or the client named in the PAC) to the requested server. S4U2Proxy is specified in the same document as S4U2Self.<br />
<br />
==Normal TGS requests==<br />
<br />
For the purposes of this article, a TGS request is considered "normal" if it:<br />
<br />
* does not have any of the forwarded, proxy, renew, validate, enc-tkt-in-skey, or cname-in-addl-tkt options<br />
* does not contain PA-FOR-USER or PA_S4U_X509_USER pa-data.<br />
<br />
The header ticket for a normal TGS request server have an sname field of krbtgt/THIS.REALM, where THIS.REALM must match the realm field of the TGS request. If the header ticket is a cross-realm TGT (the ticket's srealm field is some OTHER.REALM different from THIS.REALM), the ticket's crealm must also be different from THIS.REALM; this is called the "lineage check", and ensures that foreign realms cannot issue tickets for local users. The KDC also (unless requested not to) checks the transited list in the ticket to ensure that OTHER.REALM has the authority to issue tickets for the realm of the header ticket client, and adds OTHER.REALM to the transited list of the issued ticket if it does not match the realm of the header ticket client.<br />
<br />
If the requested server is a TGS principal for a different realm, the KDC may issue a ticket to an alternative TGS principal for an intermediate realm instead. If the requested server is not a TGS server but the request has the "canonicalize" KDC option set ({{rfcref|6803}} section 3), the KDC may issue a ticket to an outgoing TGS principal; this is called a "referral".<br />
<br />
For local clients, some KDC implementations look up the client DB entry and apply the entry's policy in case it has changed (e.g. the account has been revoked). The MIT krb5 KDC does not currently do this.<br />
<br />
It is possible for an otherwise normal TGS request to be part of a cross-realm Resource-Based Constrained Delegation (RBCD) operation transiting through this realm. In this case, the header ticket will be a cross-realm TGT, the request server will be a cross-realm TGS, the header ticket PAC will contain an S4U_DELEGATION_INFO buffer giving the ticket client as the last transited service, and the PAC_CLIENT_INFO buffer will contain a realm part in the name. These requests can be processed the same way as a normal TGS request, but when issuing a PAC for the resulting ticket the KDC must copy the PAC_CLIENT_INFO buffer from the header ticket rather than creating one for the ticket client.<br />
<br />
==Ticket modification requests==<br />
<br />
A ticket modification request has the forwarded, proxy, renew, or validate option. The header ticket is not required to be a TGT, and must not be a TGT if the proxy option is requested. The request sname must match the ticket sname, and the KDC must not be issuing a referral. The header ticket must have a flag corresponding to the requested option (forwardable for forwarded, etc.) The issued ticket will be similar in most respects to the header ticket, except for the addresses, validity times, and invalid flag as indicated by the request option.<br />
<br />
==User-to-user requests==<br />
<br />
If the enc-tkt-in-skey option is requested, the request must contain a second ticket in the additional-tickets field. The second ticket must be a local-realm TGT for the server realm (krbtgt/THIS.REALM@THIS.REALM), and the second ticket cname and crealm must match the request sname and realm. The request is processed similarly to a normal request, but the resulting ticket will be encrypted in the session key of the second ticket, and will have a session key of the same type as the second ticket's. User-to-user requests cannot generate referrals.<br />
<br />
==S4U2Self (protocol transition) requests==<br />
<br />
If the request pa-data contains an element of type PA-FOR-USER or PA_S4U_X509_USER or both, it is a request to issue a ticket from a named user (known as the "subject") to the requesting service. The subject may be identified by principal or by X.509 certificate. S4U2Self requests do not require special privileges, although in some cases the forwardable flag will be cleared on the resulting ticket. S4U2Self requests must not contain any options for other kinds of special TGS requests (ticket modification, user-to-user, and S4U2Proxy).<br />
<br />
For a local-realm S4U2Self requests, the request server must match the header ticket client, although they may use different aliases for the same principal. A PAC must be present in the header ticket, although it is not used as a basis for the PAC in the issued ticket. The subject is looked up in the database, checked for policy constraints, and a PAC is issued for it as it would be for an AS request. Authentication indicators are not copied from the header ticket, as there was no actual authentication of the subject.<br />
<br />
For cross-realm S4U2Self scenarios, there are four different kinds of requests:<br />
<br />
1. Zero or more AS requests to determine the subject realm, if it is not already known. These may be ordinary AS requests, but they may also contain PA_S4U_X509_USER if the user is identified by a certificate. The requesting service begins at the service realm and follows the chain of KDC_ERR_WRONG_REALM errors until a KDC_ERR_PREAUTH_REQUIRED error is received or a ticket is issued, indicating that the subject realm is known. The requesting server then obtains a cross-realm TGT to the subject realm using ordinary TGS requests.<br />
<br />
2. A cross-realm S4U2Self request to the subject realm. Since the requesting service does not live in this realm, the request server will contain the representation of a requesting service as an enterprise principal. As for a local S4U2Self request, the subject realm KDC looks up the subject in the database, checks it for policy constraints, and constructs a PAC for the subject. Unlike a local request, the PAC_CLIENT_INFO name in the PAC will contain an "@REALM" suffix identifying the subject realm, and the KDC issues a referral TGT back towards the service realm. The reply includes PA_S4U_X509_USER naming the subject principal, in case a certificate was used to identify it.<br />
<br />
3. Zero or more cross-realm S4U2Self requests to intermediate realms along the path back to the service realm, each resulting in a referral TGT. The S4U2Self padata in these requests must contain the subject principal name; the subject can no longer be identified by certificate at this step. As in step 2, the PAC in the issued referral TGTs must be for the subject and must contain an "@REALM" suffix in the PAC_CLIENT_INFO name.<br />
<br />
4. A cross-realm S4U2Self request to the service realm. This type of request would ordinarily fail the lineage check (as the client is in the local realm and the TGT was issued by another realm), so S4U2Self requests are excepted from this check. The service realm KDC issues a ticket from the subject to the requesting service, using the PAC in the the referral ticket as a basis. However, the PAC_CLIENT_INFO name for the PAC does not contain the "@REALM" suffix.<br />
<br />
S4U2Self requests override the no_authdata_required flag on the requesting service principal. Although the service may not require authorization data for tickets received from clients, its use of S4U2Self strongly suggests the need for a PAC--either the service plans to make an S4U2Proxy request, or it has a special need to inspect the PAC for a subject.<br />
<br />
If the requesting service has any outgoing constrained delegation privileges, but does not have the ok_to_auth_as_delegate principal flag, then the forwardable ticket flag will be suppressed on tickets issued to it via S4U2Self. The intent is to prevent the use of S4U2Self-issued tickets as S4U2Proxy evidence tickets without this extra privilege when outgoing authorizations are used (but not when the delegation is allowed by an incoming authorization on the delegation target).<br />
<br />
S4U2Self is fully specified in [http://msdn.microsoft.com/en-us/library/cc246071(PROT.13).aspx [MS-SFU]].</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=TGS_Requests&diff=6023TGS Requests2021-12-09T01:07:38Z<p>Ghudson: </p>
<hr />
<div>Kerberos Ticket Granting Service (TGS) requests are one of the most complicated areas of processing in MIT krb5, in both the client and the KDC. Here are some notes on the different kind of TGS requests and what considerations must be made when processing them.<br />
<br />
==Protocol structure==<br />
<br />
Like an AS request, a TGS request contains a KDC-REQ-BODY sequence and a sequence of PA-DATA. One of the pa-data elements will have type PA-TGS-REQ; its value will contain an AP-REQ, the same protocol structure a client would use to authenticate to an application server. The ticket in the AP-REQ is called the "header ticket" within the MIT KDC source code, because {{rfcref|4120}} uses the term "authentication header" to refer to the AP-REQ.<br />
<br />
The authenticator in the AP-REQ contains a checksum over the encoding of the body. This checksum need not be keyed, as it is contained within an encrypted payload, but with modern encryption types it is usually a keyed checksum anyway. There is no intrinsic cryptographic binding between other padata elements and the PA-TGS-REQ or the body.<br />
<br />
The authenticator in the AP-REQ may contain a subkey, in which case the TGS response should be encrypted in the subkey. Otherwise it should be encrypted in the session key of the header ticket. There are four historical interoperability bugs affecting the use of subkeys in TGS requests, as described here:<br />
<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/DD8CFMuWiHJhkkoHGbjx0Z1dpKo<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/4qhYxn7iovCnfsHL8wmim7-8Tq0<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/hl6PvUz94IQMFadSybnjGYeBCCE<br />
<br />
TGS requests may use FAST implicit armor ({{rfcref|6113}} section 5.4). In this case one of the pa-data elements will have type PA-FX-FAST and its value will contain a second copy of the TGS request encrypted in a key derived from the subkey (which must be present) and the ticket session key.<br />
<br />
==Types of TGS requests==<br />
<br />
* Normal<br />
<br />
* Ticket modification<br />
<br />
* User-to-user<br />
<br />
* S4U2Self (aka "protocol transition"): if the request pa-data contains an element of type PA-FOR-USER or PA_S4U_X509_USER or both, it is a request to issue a ticket from a named user to the requesting service. S4U2Self is specified in [http://msdn.microsoft.com/en-us/library/cc246071(PROT.13).aspx [MS-SFU]].<br />
<br />
* S4U2Proxy (aka "constrained delegation"): if the CNAME-IN-ADDL-TICKET option is requested, the request body must contain an additional ticket (called the "evidence ticket") from a user to the requesting service--or, for a cross-realm request, a cross-TGT containing a PAC or equivalent authorization data for a user. If delegation is allowed to the requested server, the KDC issues a ticket from the evidence ticket client (or the client named in the PAC) to the requested server. S4U2Proxy is specified in the same document as S4U2Self.<br />
<br />
==Normal TGS requests==<br />
<br />
For the purposes of this article, a TGS request is considered "normal" if it:<br />
<br />
* does not have any of the forwarded, proxy, renew, validate, enc-tkt-in-skey, or cname-in-addl-tkt options<br />
* does not contain PA-FOR-USER or PA_S4U_X509_USER pa-data.<br />
<br />
The header ticket for a normal TGS request server have an sname field of krbtgt/THIS.REALM, where THIS.REALM must match the realm field of the TGS request. If the header ticket is a cross-realm TGT (the ticket's srealm field is some OTHER.REALM different from THIS.REALM), the ticket's crealm must also be different from THIS.REALM; this is called the "lineage check", and ensures that foreign realms cannot issue tickets for local users. The KDC also (unless requested not to) checks the transited list in the ticket to ensure that OTHER.REALM has the authority to issue tickets for the realm of the header ticket client, and adds OTHER.REALM to the transited list of the issued ticket if it does not match the realm of the header ticket client.<br />
<br />
If the requested server is a TGS principal for a different realm, the KDC may issue a ticket to an alternative TGS principal for an intermediate realm instead. If the requested server is not a TGS server but the request has the "canonicalize" KDC option set ({{rfcref|6803}} section 3), the KDC may issue a ticket to an outgoing TGS principal; this is called a "referral".<br />
<br />
For local clients, some KDC implementations look up the client DB entry and apply the entry's policy in case it has changed (e.g. the account has been revoked). The MIT krb5 KDC does not currently do this.<br />
<br />
It is possible for an otherwise normal TGS request to be part of a cross-realm Resource-Based Constrained Delegation (RBCD) operation transiting through this realm. In this case, the header ticket will be a cross-realm TGT, the request server will be a cross-realm TGS, the header ticket PAC will contain an S4U_DELEGATION_INFO buffer giving the ticket client as the last transited service, and the PAC_CLIENT_INFO buffer will contain a realm part in the name. These requests can be processed the same way as a normal TGS request, but when issuing a PAC for the resulting ticket the KDC must copy the PAC_CLIENT_INFO buffer from the header ticket rather than creating one for the ticket client.<br />
<br />
==Ticket modification requests==<br />
<br />
A ticket modification request has the forwarded, proxy, renew, or validate option. The header ticket is not required to be a TGT, and must not be a TGT if the proxy option is requested. The request sname must match the ticket sname, and the KDC must not be issuing a referral. The header ticket must have a flag corresponding to the requested option (forwardable for forwarded, etc.) The issued ticket will be similar in most respects to the header ticket, except for the addresses, validity times, and invalid flag as indicated by the request option.<br />
<br />
==User-to-user requests==<br />
<br />
If the enc-tkt-in-skey option is requested, the request must contain a second ticket in the additional-tickets field. The second ticket must be a local-realm TGT for the server realm (krbtgt/THIS.REALM@THIS.REALM), and the second ticket cname and crealm must match the request sname and realm. The request is processed similarly to a normal request, but the resulting ticket will be encrypted in the session key of the second ticket, and will have a session key of the same type as the second ticket's. User-to-user requests cannot generate referrals.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=TGS_Requests&diff=6022TGS Requests2021-12-09T00:45:49Z<p>Ghudson: </p>
<hr />
<div>Kerberos Ticket Granting Service (TGS) requests are one of the most complicated areas of processing in MIT krb5, in both the client and the KDC. Here are some notes on the different kind of TGS requests and what considerations must be made when processing them.<br />
<br />
==Protocol structure==<br />
<br />
Like an AS request, a TGS request contains a KDC-REQ-BODY sequence and a sequence of PA-DATA. One of the pa-data elements will have type PA-TGS-REQ; its value will contain an AP-REQ, the same protocol structure a client would use to authenticate to an application server. The ticket in the AP-REQ is called the "header ticket" within the MIT KDC source code, because {{rfcref|4120}} uses the term "authentication header" to refer to the AP-REQ.<br />
<br />
The authenticator in the AP-REQ contains a checksum over the encoding of the body. This checksum need not be keyed, as it is contained within an encrypted payload, but with modern encryption types it is usually a keyed checksum anyway. There is no intrinsic cryptographic binding between other padata elements and the PA-TGS-REQ or the body.<br />
<br />
The authenticator in the AP-REQ may contain a subkey, in which case the TGS response should be encrypted in the subkey. Otherwise it should be encrypted in the session key of the header ticket. There are four historical interoperability bugs affecting the use of subkeys in TGS requests, as described here:<br />
<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/DD8CFMuWiHJhkkoHGbjx0Z1dpKo<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/4qhYxn7iovCnfsHL8wmim7-8Tq0<br />
https://mailarchive.ietf.org/arch/msg/krb-wg/hl6PvUz94IQMFadSybnjGYeBCCE<br />
<br />
TGS requests may use FAST implicit armor ({{rfcref|6113}} section 5.4). In this case one of the pa-data elements will have type PA-FX-FAST and its value will contain a second copy of the TGS request encrypted in a key derived from the subkey (which must be present) and the ticket session key.<br />
<br />
==Types of TGS requests==<br />
<br />
* Normal<br />
<br />
* Ticket modification: if the RENEW, VALIDATE, or PROXY option is requested, the header ticket server need not be a TGT (and must not be a TGT for PROXY), but the requested server must match the header ticket server. The RENEW option is frequently used in practice, while the VALIDATE and PROXY options are not.<br />
<br />
* User-to-user: if the ENC-TKT-IN-SKEY option is requested, the request body must contain an additional ticket, whose client must match the requested server and whose server must be the local TGS (krbtgt/THIS.REALM@THIS.REALM). The issued ticket will be encrypted in the session key of the second ticket, not in the long-term key of the service principal.<br />
<br />
* S4U2Self (aka "protocol transition"): if the request pa-data contains an element of type PA-FOR-USER or PA_S4U_X509_USER or both, it is a request to issue a ticket from a named user to the requesting service. S4U2Self is specified in [http://msdn.microsoft.com/en-us/library/cc246071(PROT.13).aspx [MS-SFU]].<br />
<br />
* S4U2Proxy (aka "constrained delegation"): if the CNAME-IN-ADDL-TICKET option is requested, the request body must contain an additional ticket (called the "evidence ticket") from a user to the requesting service--or, for a cross-realm request, a cross-TGT containing a PAC or equivalent authorization data for a user. If delegation is allowed to the requested server, the KDC issues a ticket from the evidence ticket client (or the client named in the PAC) to the requested server. S4U2Proxy is specified in the same document as S4U2Self.<br />
<br />
==Normal TGS requests==<br />
<br />
For the purposes of this article, a TGS request is considered "normal" if it:<br />
<br />
* does not have any of the forwarded, proxy, renew, validate, enc-tkt-in-skey, or cname-in-addl-tkt options<br />
* does not contain PA-FOR-USER or PA_S4U_X509_USER pa-data.<br />
<br />
The header ticket for a normal TGS request server must be a TGT, meaning its sname field is krbtgt/THIS.REALM. If it is a cross-realm TGT (the srealm field is some OTHER.REALM different from THIS.REALM), the ticket's crealm must also be different from THIS.REALM; this is called the "lineage check", and ensures that foreign realms cannot issue tickets for local users. The KDC also (unless requested not to) checks the transited list in the ticket to ensure that OTHER.REALM has the authority to issue tickets for the realm of the header ticket client, and adds OTHER.REALM to the transited list of the issued ticket if it does not match the realm of the header ticket client.<br />
<br />
If the requested server is a TGS principal for a different realm, the KDC may issue a ticket to an alternative TGS principal for an intermediate realm instead. If the requested server is not a TGS server but the request has the "canonicalize" KDC option set ({{rfcref|6803}} section 3), the KDC may issue a ticket to an outgoing TGS principal; this is called a "referral".<br />
<br />
For local clients, some KDC implementations look up the client DB entry and apply the entry's policy in case it has changed (e.g. the account has been revoked). The MIT krb5 KDC does not currently do this.<br />
<br />
It is possible for an otherwise normal TGS request to be part of a cross-realm Resource-Based Constrained Delegation (RBCD) operation transiting through this realm. In this case, the header ticket will be a cross-realm TGT, the request server will be a cross-realm TGS, the header ticket PAC will contain an S4U_DELEGATION_INFO buffer giving the ticket client as the last transited service, and the PAC_CLIENT_INFO buffer will contain a realm part in the name. These requests can be processed the same way as a normal TGS request, but when issuing a PAC for the resulting TGT the KDC must copy the PAC_CLIENT_INFO values from the header ticket rather than issuing one for the ticket client.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Kerberos.org_server_configuration&diff=6021Kerberos.org server configuration2021-08-06T16:40:35Z<p>Ghudson: /* BIND configuration */</p>
<hr />
<div>This page documents the service configuration on kerberos.org (current canonical name kerborg-prod-app-2.mit.edu), which runs a web server, a wiki, and a DNS name server.<br />
<br />
==Packages==<br />
<br />
The apache2, bind9, certbot, mediawiki, and python3-certbot-apache packages are required.<br />
<br />
==Web server configuration==<br />
<br />
The static web page content is located in /var/www.<br />
<br />
The Apache HTTP server configuration can be found in the krbdev-services repository under kerborg-apache. kerborg.cnf should be installed in /etc/ssl/private; the rest go in /etc/apache2/sites-available. Run the following commands to enable the correct configuration files:<br />
<br />
a2ensite 000-default-kerberos-org.conf<br />
a2ensite k5wiki.conf<br />
a2dissite 000-default.conf<br />
a2enmod rewrite<br />
a2enmod ssl<br />
<br />
The letsencrypt TLS certificate is generated using certbot:<br />
<br />
certbot --apache -d 'kerberos.org,www.kerberos.org,k5wiki.kerberos.org,test.kerberos.org,www.test.kerberos.org,k5wiki.test.kerberos.org,kerberos.net,www.kerberos.net' certonly<br />
<br />
letsencrypt certificates only last 90 days, but a systemd timer installed by the certbot package will automatically renew the certificate when it approaches expiration.<br />
<br />
==Mediawiki configuration==<br />
<br />
/etc/mediawiki/LocalSettings.php and /etc/mediawiki/Secrets.php contain the wiki configuration. Secrets.php must be readable by the web server; this is currently enabled by making it more 640 and owned by group www-data.<br />
<br />
The wiki contents are stored in a MySQL database named "wikidb". This can be dumped with "mysqldump --databases wikidb > /somepath" and loaded with "mysql < /somepath".<br />
<br />
A MySQL user named "wikiuser" must be created to access the database. To create it run the following commands inside mysql:<br />
<br />
create user wikiuser@localhost identified by '<password>';<br />
grant all privileges on `wikidb`.* to 'wikiuser'@'localhost';<br />
<br />
Use the password from /etc/mediawiki/Secrets.php.<br />
<br />
If migrating to a server with a new version of Mediawiki, the database must be upgraded. Navigate to /wm-config on the new server and follow instructions.<br />
<br />
==Database backups==<br />
<br />
Install /mit/ops/services/mysql/mysqlbackup_java.sh in /usr/local/sbin and make it mode 755. Modify the script to use /bin/bzip2 instead of /usr/bin/bzip2, and delete the three java invocations (which are for monitoring).<br />
<br />
/usr/local/etc/mysqlbackup_java.conf contains the database password (PASS=xxxxx) and specifies COMPRESS=yes. Make it mode 600.<br />
<br />
Create a MySQL user for backups by running the following within mysql:<br />
<br />
create user 'dba-backup'@localhost identified by '<password>';<br />
grant select, process, file, lock tables, show view on *.* to 'dba-backup'@'localhost;<br />
<br />
Add the following root cron job:<br />
<br />
00 23 * * * /usr/local/sbin/mysqlbackup_java.sh >/dev/null 2>&1<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records. Make sure to edit the records for kerberos.net as well as kerberos.org.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6020RT server configuration2021-06-01T23:52:38Z<p>Ghudson: /* Testing */</p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
<br />
Some of the above accounts may be created by ops during provisioning. /var/rt2 and /var/rt2/.ssh must be owned by rtcvs or sshd will reject logins as rtcvs from drugstore.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
ticket: new<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rtcvs, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6019RT server configuration2021-06-01T23:44:06Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
<br />
Some of the above accounts may be created by ops during provisioning. /var/rt2 and /var/rt2/.ssh must be owned by rtcvs or sshd will reject logins as rtcvs from drugstore.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rtcvs, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6018RT server configuration2021-06-01T22:42:39Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
<br />
Some of the above accounts may be created by ops during provisioning. /var/rt2 and /var/rt2/.ssh must be owned by rtcvs or sshd will reject logins as rtcvs from drugstore.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Developer_chat&diff=6017Developer chat2021-06-01T22:36:22Z<p>Ghudson: </p>
<hr />
<div>MIT Kerberos developers use several venues for instant message chat.<br />
<br />
== IRC channels ==<br />
<br />
The main IRC channel for MIT Kerberos development is <code>#krbdev</code> on Libera Chat. There is a separate channel, <code>#kerberos</code>, for general Kerberos discussion and support.<br />
<br />
For more information about Libera Chat, see https://libera.chat/.<br />
<br />
The <code>#krbdev</code> channel is logged at http://colabti.org/irclogger/irclogger_logs/krbdev using the colabti.org service, which generously offers IRC logging to Free / Open Source projects.<br />
<br />
The <code>#krbdev</code> channel was previously logged by lopbot, courtesy of Brandon Allbery. These logs are no longer readily available online. Despite the possible existence of logging, please summarize important conversations to more permanent places, such as an appropriate mailing list or wiki page.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6016RT server configuration2021-06-01T19:50:49Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
The server host acts as an authoritative name server for the kerberos.org zone, so the bind9 package must be installed.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
bind9<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6015RT server configuration2021-05-26T14:43:32Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu and rt-comment@kerborg-prod-app-1.mit.edu are authorized as non-member senders at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6014RT server configuration2021-05-11T22:44:16Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu is authorized as a non-member sender at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6013RT server configuration2021-05-07T05:23:43Z<p>Ghudson: /* Postfix configuration */</p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
Make sure rt@kerborg-prod-app-1.mit.edu is authorized as a non-member sender at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/privacy/sender .<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6012RT server configuration2021-05-07T00:00:29Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes and restore the database from a dump file.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6011RT server configuration2021-05-06T23:47:07Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
request-tracker4<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes an restore the database from a dump file.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6010RT server configuration2021-05-06T22:17:07Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
As root, run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
As rtcvs ("su -s /bin/bash - rtcvs"), run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
To test rt-cvsgate, create a test message in /tmp/testmsg like so:<br />
<br />
id: NNNN (use the ticket number printed by rt-reserve-ticket above)<br />
ticket: new<br />
subject: rt-cvsgate test<br />
tags: pullup<br />
<br />
test commit message<br />
<br />
As rt-cvsgate, run "/var/rt2/bin/rt-cvsgate ''username'' < /tmp/testmsg", where ''username'' is an authorized user.<br />
<br />
Undo the temporary changes an restore the database from a dump file.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6009RT server configuration2021-05-06T20:30:29Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/.ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
Run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
Run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
[TBD: testing rt-cvsgate]</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6008RT server configuration2021-05-06T17:15:03Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
* RT site name: krbdev.mit.edu<br />
* handle RT_SiteConfig.pm permissions: yes<br />
* use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
Run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
Run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
[TBD: testing rt-cvsgate]</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6007RT server configuration2021-05-06T16:16:28Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
RT site name: krbdev.mit.edu<br />
handle RT_SiteConfig.pm permissions: yes<br />
use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
Create /var/psqlbackups (owned by root).<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart<br />
<br />
==Testing==<br />
<br />
Get a certificate for the new VM's real hostname and temporarily point /etc/apache2/ssl.crt/server.crt at it.<br />
<br />
In /etc/request-tracker4/RT_SiteConfig.pm, temporarily set @ReferrerWhitelist to use the real hostname instead of krbdev.mit.edu.<br />
<br />
Temporarily set emergency moderation on the krb5-bugs mailing list (at https://mailman.mit.edu:444/mailman/admin/krb5-bugs/general ) to ensure that mail sent to that list as the result of testing is caught in the moderation queue.<br />
<br />
Verify that RT displays at https://realhostname/rt and tickets can be accessed. Verify that https://realhostname:444/ works and that a new ticket can be created. Respond to the ticket via email and verify that the response is stored in the ticket.<br />
<br />
Run /var/rt2/bin/rt-reserve-ticket and verify that a ticket number is printed.<br />
<br />
Run /var/rt2/bin/krb5-daily.sh and verify that a dump file appears in /var/psqlbackups.<br />
<br />
[TBD: testing rt-cvsgate]</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6006RT server configuration2021-05-06T05:53:10Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
RT site name: krbdev.mit.edu<br />
handle RT_SiteConfig.pm permissions: yes<br />
use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /usr/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/usr/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6005RT server configuration2021-05-06T05:52:09Z<p>Ghudson: Update for Ubuntu 20.04</p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name kerborg-prod-app-1.mit.edu), which runs Ubuntu 20.04.<br />
<br />
==Packages==<br />
<br />
In Ubuntu 20.04, the request-tracker4 package contains a suitable version of RT. This package will ask some questions at installation time:<br />
<br />
RT site name: krbdev.mit.edu<br />
handle RT_SiteConfig.pm permissions: yes<br />
use dbconfig-common: no<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fcgid package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
libapache2-mod-fcgid<br />
libsendmail-pmilter-perl<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
Create /var/rt2/bin and copy in the following scripts from the krbdev-services repository:<br />
<br />
rt-scripts/rt-reserve-ticket<br />
rt-scripts/rtmilter.pl<br />
rt-scripts/krb5-daily.sh<br />
rt-cvs/rt-cvsgate<br />
<br />
The scripts and directory should be mode 755 and owned by user rt and group rt.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
The rt user account is not actually needed for the current RT installation, and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /etc/request-tracker4.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /opt/rt4/sbin/rt-clean-sessions<br />
0 4 * * * /var/rt2/bin/krb5-daily.sh<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/opt/rt4/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "zcat /path/to/dump.gz | psql -d rt4 -Upostgres"<br />
<br />
==Postfix configuration==<br />
<br />
By default ops manages Postfix with Puppet. This must be disabled by ops, and the Debian defaults restored by copying /usr/share/postfix/main.cf.debian to /etc/postfix/main.cf and /usr/share/postfix/master.cf.dist to /etc/postfix/master.cf.<br />
<br />
At the end of /etc/postfix/main.cf add:<br />
<br />
myhostname = krbdev.mit.edu<br />
mydestination = krbdev.mit.edu, kerborg-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Edit /etc/apache2/ports.conf and add "Listen 444" in the ssl_module section after "Listen 443".<br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=6004RT server configuration2021-02-17T17:30:24Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name krbdev-prod-app-1.mit.edu), which runs Ubuntu 16.04.<br />
<br />
==Packages==<br />
<br />
Some of RT's Perl dependencies are too new for Ubuntu 16.04's package repository. Therefore we allow RT's build system to use CPAN to fetch dependencies. Before doing this it is necessary to configure CPAN once with:<br />
<br />
perl -MCPAN -e shell<br />
<br />
and then exit out of the shell.<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fastcgi package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
apache2-suexec-pristine<br />
libapache-session-perl<br />
libapache2-mod-fastcgi<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
The rt user account is not actually needed for the current RT installation (although the rt group is), and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Our installation of Request Tracker is an unmodified version 4.4.4. The source code is present in /usr/src and is configured as follows:<br />
<br />
./configure --with-bin-owner=rt --with-libs-owner=rt --with-libs-group=rt \<br />
--with-db-type=Pg --with-db-host='' \<br />
--with-web-user=www-data --with-web-group=www-data<br />
make fixdeps (hit return to accept defaults as necessary)<br />
make testdeps<br />
make install<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /opt/rt4/etc.<br />
<br />
Several scripts come from the krbdev-services repository, in the rt-cvs and rt-scripts directories. All are installed in /var/rt2/bin.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
MAILTO=krbcore-hw@mit.edu<br />
0 3 * * * /var/rt2/bin/krb5-daily.sh<br />
0 4 * * * /opt/rt4/sbin/rt-clean-sessions<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/opt/rt4/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "pg_restore -d rt4 -Upostgres /path/to/dumpfile".<br />
<br />
==Postfix configuration==<br />
<br />
In /etc/postfix/main.cf:<br />
<br />
* Set myhostname = krbdev.mit.edu<br />
* Set mydestination = krbdev.mit.edu, krbdev-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
* Add the following to the end:<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Kerberos.org_server_configuration&diff=6003Kerberos.org server configuration2021-01-26T18:32:40Z<p>Ghudson: </p>
<hr />
<div>This page documents the service configuration on kerberos.org (current canonical name kerborg-prod-app-2.mit.edu), which runs a web server, a wiki, and a DNS name server.<br />
<br />
==Packages==<br />
<br />
The apache2, bind9, certbot, mediawiki, and python3-certbot-apache packages are required.<br />
<br />
==Web server configuration==<br />
<br />
The static web page content is located in /var/www.<br />
<br />
The Apache HTTP server configuration can be found in the krbdev-services repository under kerborg-apache. kerborg.cnf should be installed in /etc/ssl/private; the rest go in /etc/apache2/sites-available. Run the following commands to enable the correct configuration files:<br />
<br />
a2ensite 000-default-kerberos-org.conf<br />
a2ensite k5wiki.conf<br />
a2dissite 000-default.conf<br />
a2enmod rewrite<br />
a2enmod ssl<br />
<br />
The letsencrypt TLS certificate is generated using certbot:<br />
<br />
certbot --apache -d 'kerberos.org,www.kerberos.org,k5wiki.kerberos.org,test.kerberos.org,www.test.kerberos.org,k5wiki.test.kerberos.org,kerberos.net,www.kerberos.net' certonly<br />
<br />
letsencrypt certificates only last 90 days, but a systemd timer installed by the certbot package will automatically renew the certificate when it approaches expiration.<br />
<br />
==Mediawiki configuration==<br />
<br />
/etc/mediawiki/LocalSettings.php and /etc/mediawiki/Secrets.php contain the wiki configuration. Secrets.php must be readable by the web server; this is currently enabled by making it more 640 and owned by group www-data.<br />
<br />
The wiki contents are stored in a MySQL database named "wikidb". This can be dumped with "mysqldump --databases wikidb > /somepath" and loaded with "mysql < /somepath".<br />
<br />
A MySQL user named "wikiuser" must be created to access the database. To create it run the following commands inside mysql:<br />
<br />
create user wikiuser@localhost identified by '<password>';<br />
grant all privileges on `wikidb`.* to 'wikiuser'@'localhost';<br />
<br />
Use the password from /etc/mediawiki/Secrets.php.<br />
<br />
If migrating to a server with a new version of Mediawiki, the database must be upgraded. Navigate to /wm-config on the new server and follow instructions.<br />
<br />
==Database backups==<br />
<br />
Install /mit/ops/services/mysql/mysqlbackup_java.sh in /usr/local/sbin and make it mode 755. Modify the script to use /bin/bzip2 instead of /usr/bin/bzip2, and delete the three java invocations (which are for monitoring).<br />
<br />
/usr/local/etc/mysqlbackup_java.conf contains the database password (PASS=xxxxx) and specifies COMPRESS=yes. Make it mode 600.<br />
<br />
Create a MySQL user for backups by running the following within mysql:<br />
<br />
create user 'dba-backup'@localhost identified by '<password>';<br />
grant select, process, file, lock tables, show view on *.* to 'dba-backup'@'localhost;<br />
<br />
Add the following root cron job:<br />
<br />
00 23 * * * /usr/local/sbin/mysqlbackup_java.sh >/dev/null 2>&1<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Kerberos.org_server_configuration&diff=6002Kerberos.org server configuration2021-01-26T17:51:02Z<p>Ghudson: /* Packages */</p>
<hr />
<div>This page documents the service configuration on kerberos.org (current canonical name kerborg-prod-app-2.mit.edu), which runs a web server, a wiki, and a DNS name server.<br />
<br />
==Packages==<br />
<br />
The apache2, bind9, certbot, mediawiki, and python3-certbot-apache packages are required.<br />
<br />
==Web server configuration==<br />
<br />
The static web page content is located in /var/www.<br />
<br />
The Apache HTTP server configuration can be found in the krbdev-services repository under kerborg-apache. kerborg.cnf should be installed in /etc/ssl/private; the rest go in /etc/apache2/sites-available. Run the following commands to enable the correct configuration files:<br />
<br />
a2ensite 000-default-kerberos-org.conf<br />
a2ensite k5wiki.conf<br />
a2dissite 000-default.conf<br />
a2enmod rewrite<br />
a2enmod ssl<br />
<br />
==Mediawiki configuration==<br />
<br />
/etc/mediawiki/LocalSettings.php and /etc/mediawiki/Secrets.php contain the wiki configuration. Secrets.php must be readable by the web server; this is currently enabled by making it more 640 and owned by group www-data.<br />
<br />
The wiki contents are stored in a MySQL database named "wikidb". This can be dumped with "mysqldump --databases wikidb > /somepath" and loaded with "mysql < /somepath".<br />
<br />
A MySQL user named "wikiuser" must be created to access the database. To create it run the following commands inside mysql:<br />
<br />
create user wikiuser@localhost identified by '<password>';<br />
grant all privileges on `wikidb`.* to 'wikiuser'@'localhost';<br />
<br />
Use the password from /etc/mediawiki/Secrets.php.<br />
<br />
If migrating to a server with a new version of Mediawiki, the database must be upgraded. Navigate to /wm-config on the new server and follow instructions.<br />
<br />
==Database backups==<br />
<br />
Install /mit/ops/services/mysql/mysqlbackup_java.sh in /usr/local/sbin and make it mode 755. Modify the script to use /bin/bzip2 instead of /usr/bin/bzip2, and delete the three java invocations (which are for monitoring).<br />
<br />
/usr/local/etc/mysqlbackup_java.conf contains the database password (PASS=xxxxx) and specifies COMPRESS=yes. Make it mode 600.<br />
<br />
Create a MySQL user for backups by running the following within mysql:<br />
<br />
create user 'dba-backup'@localhost identified by '<password>';<br />
grant select, process, file, lock tables, show view on *.* to 'dba-backup'@'localhost;<br />
<br />
Add the following root cron job:<br />
<br />
00 23 * * * /usr/local/sbin/mysqlbackup_java.sh >/dev/null 2>&1<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6001Release engineering notes2020-11-29T20:06:08Z<p>Ghudson: </p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y" and push to the authoritative repository.<br />
* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1).<br />
** In README, copy the list of contributors from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=6000Release engineering notes2020-11-03T19:57:00Z<p>Ghudson: </p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y" and push to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1).<br />
** In README, copy the list of contributors from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code> (only for minor releases, not patch releases)<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Kerberos.org_server_configuration&diff=5999Kerberos.org server configuration2020-09-03T19:31:58Z<p>Ghudson: Created page with "This page documents the service configuration on kerberos.org (current canonical name kerborg-prod-app-2.mit.edu), which runs a web server, a wiki, and a DNS name server. ==P..."</p>
<hr />
<div>This page documents the service configuration on kerberos.org (current canonical name kerborg-prod-app-2.mit.edu), which runs a web server, a wiki, and a DNS name server.<br />
<br />
==Packages==<br />
<br />
The apache2, bind9, and mediawiki packages are required.<br />
<br />
==Web server configuration==<br />
<br />
The static web page content is located in /var/www.<br />
<br />
The Apache HTTP server configuration can be found in the krbdev-services repository under kerborg-apache. kerborg.cnf should be installed in /etc/ssl/private; the rest go in /etc/apache2/sites-available. Run the following commands to enable the correct configuration files:<br />
<br />
a2ensite 000-default-kerberos-org.conf<br />
a2ensite k5wiki.conf<br />
a2dissite 000-default.conf<br />
a2enmod rewrite<br />
a2enmod ssl<br />
<br />
==Mediawiki configuration==<br />
<br />
/etc/mediawiki/LocalSettings.php and /etc/mediawiki/Secrets.php contain the wiki configuration. Secrets.php must be readable by the web server; this is currently enabled by making it more 640 and owned by group www-data.<br />
<br />
The wiki contents are stored in a MySQL database named "wikidb". This can be dumped with "mysqldump --databases wikidb > /somepath" and loaded with "mysql < /somepath".<br />
<br />
A MySQL user named "wikiuser" must be created to access the database. To create it run the following commands inside mysql:<br />
<br />
create user wikiuser@localhost identified by '<password>';<br />
grant all privileges on `wikidb`.* to 'wikiuser'@'localhost';<br />
<br />
Use the password from /etc/mediawiki/Secrets.php.<br />
<br />
If migrating to a server with a new version of Mediawiki, the database must be upgraded. Navigate to /wm-config on the new server and follow instructions.<br />
<br />
==Database backups==<br />
<br />
Install /mit/ops/services/mysql/mysqlbackup_java.sh in /usr/local/sbin and make it mode 755. Modify the script to use /bin/bzip2 instead of /usr/bin/bzip2, and delete the three java invocations (which are for monitoring).<br />
<br />
/usr/local/etc/mysqlbackup_java.conf contains the database password (PASS=xxxxx) and specifies COMPRESS=yes. Make it mode 600.<br />
<br />
Create a MySQL user for backups by running the following within mysql:<br />
<br />
create user 'dba-backup'@localhost identified by '<password>';<br />
grant select, process, file, lock tables, show view on *.* to 'dba-backup'@'localhost;<br />
<br />
Add the following root cron job:<br />
<br />
00 23 * * * /usr/local/sbin/mysqlbackup_java.sh >/dev/null 2>&1<br />
<br />
==BIND configuration==<br />
<br />
The bind9 configuration files can be found in krbdev-services under bind. They should be installed under /etc/bind. "rndc reload" will restart the runing named with the changed configuration. If it is necessary to edit any of the zone files, be sure to update the serial number in the SOA record to the current date followed by "00" (or "01" etc. for successive edits in the same day).<br />
<br />
If the IP address if kerberos.org needs to be changed, the glue record at hover.com must be updated. In the current Hover UI, glue records can be found under "advanced". The transfer lock on the domain must be temporarily disabled (via the Overview screen) to update glue records.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=RT_server_configuration&diff=5998RT server configuration2020-04-18T23:01:28Z<p>Ghudson: /* Apache httpd configuration */</p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 RT server. The current server is krbdev.mit.edu (canonical name krbdev-prod-app-1.mit.edu), which runs Ubuntu 16.04.<br />
<br />
==Packages==<br />
<br />
Some of RT's Perl dependencies are too new for Ubuntu 16.04's package repository. Therefore we allow RT's build system to use CPAN to fetch dependencies. Before doing this it is necessary to configure CPAN once with:<br />
<br />
perl -MCPAN -e shell<br />
<br />
and then exit out of the shell.<br />
<br />
The data in RT is stored in a PostgreSQL database. The postgresql Ubuntu package will install the recommended version of PostgreSQL for the current Ubuntu version.<br />
<br />
The mail interface to RT is handled by Postfix, so the postfix package is required. The libsendmail-pmilter-perl package is required for the custom milter script.<br />
<br />
The web front end to RT is an Apache2 web server, so the apache2 package is required. RT uses a FastCGI server, so the libapache2-mod-fastcgi package is required.<br />
<br />
In sum, the following packages must be installed on the RT server:<br />
<br />
apache2<br />
apache2-suexec-pristine<br />
libapache-session-perl<br />
libapache2-mod-fastcgi<br />
perl<br />
perl-base<br />
perl-modules<br />
postfix<br />
postgresql<br />
<br />
==User accounts==<br />
<br />
The postgresql package will create a postgres user account.<br />
<br />
The following user accounts and group entries must be created manually:<br />
<br />
* group rt<br />
* user rt: primary group rt, homedir /var/rt2, shell /bin/false<br />
* user rtcvs: primary group rt, homedir /var/rt2, shell /bin/sh<br />
<br />
These accounts could be created with:<br />
<br />
groupadd -r rt<br />
useradd -r -m -g rt -d /var/rt2 -s /bin/false rt<br />
useradd -r -g rt -d /var/rt2 rtcvs<br />
<br />
Some of the above accounts may be created by ops during provisioning.<br />
<br />
/var/rt2 should contain an empty .k5login file, managed by ops. It should contain a .ssh/authorized_keys file, managed by ops, containing the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu.<br />
<br />
The rt user account is not actually needed for the current RT installation (although the rt group is), and the homedir name /var/rt2 is outdated. The following references need to be taken into account when changing the user and group configuration:<br />
<br />
* Both the rt and rtcvs accounts have the homedir /var/rt2.<br />
* krb5-daily.sh references the krbsnap.keytab file and dumps directory in /var/rt2.<br />
* A root cron job runs krb5-daily.sh from /var/rt2.<br />
* A root cron job runs rtmilter on boot from /var/rt2.<br />
* The empty /var/rt2/.k5login file is managed by ops.<br />
* The /var/rt2/ssh/authorized_keys file is managed by ops.<br />
* On drugstore.mit.edu, the krb5 git repository rt-ssh-cmd config value references the rtcvs user and /var/rt2/bin/rt-cvsgate.<br />
* On drugstore.mit.edu, the krb5 git repository hooks/krb5-rt-id script references the rtcvs user and /var/rt2/bin/rt-reserve-ticket. This script comes from the krbdev-services repository's githooks/krb5-rt-id.<br />
* Some of the same references are present in the krbdev-services repository, but they aren't used.<br />
<br />
==RT setup==<br />
<br />
Our installation of Request Tracker is an unmodified version 4.4.4. The source code is present in /usr/src and is configured as follows:<br />
<br />
./configure --with-bin-owner=rt --with-libs-owner=rt --with-libs-group=rt \<br />
--with-db-type=Pg --with-db-host='' \<br />
--with-web-user=www-data --with-web-group=www-data<br />
make fixdeps (hit return to accept defaults as necessary)<br />
make testdeps<br />
make install<br />
<br />
Install the RT_SiteConfig.pm file from the krbdev-services repository in /opt/rt4/etc.<br />
<br />
Several scripts come from the krbdev-services repository, in the rt-cvs and rt-scripts directories. All are installed in /var/rt2/bin.<br />
<br />
In root's crontab file ("crontab -e" as root), add the following to perform daily maintenance:<br />
<br />
0 3 * * * /var/rt2/bin/krb5-daily.sh<br />
0 4 * * * /opt/rt4/sbin/rt-clean-sessions<br />
<br />
==PostgreSQL configuration==<br />
<br />
Many PostgreSQL files live in directories specific to the PostgreSQL major and minor version, such as /etc/postgresql/8.3 for PostgreSQL 8.3.<br />
<br />
The Ubuntu postgresql package will create a "main" cluster with a configuration directory in /etc/postgresql/<version>/main.<br />
<br />
In /etc/postgresql/<version>/main/pg_ident.conf, add:<br />
<br />
local root root<br />
local root postgres<br />
local root rt_user<br />
local rt rt_user<br />
local rtcvs rt_user<br />
local postfix rt_user<br />
local nobody rt_user<br />
local www-data rt_user<br />
<br />
(The entry for "rt" should no longer be needed, but is currently still present.)<br />
<br />
In /etc/postgresql/<version>/main/pg_hba.conf, find the line that reads "local all all peer" and add "map=local" to the end, so it reads "local all all peer map=local". Comment out the line that reads "local all postgres peer", despite the warning not to disable it. Run "service postgresql restart" to reread the affected files. Run "psql -Upostgres --list" to verify that the identity map works.<br />
<br />
Run "createuser -Upostgres rt_user" to create the rt_user role.<br />
<br />
Run "/opt/rt4/sbin/rt-setup-database --action create" to create the database, then restore it from a backup with "pg_restore -d rt4 -Upostgres /path/to/dumpfile".<br />
<br />
==Postfix configuration==<br />
<br />
In /etc/postfix/main.cf:<br />
<br />
* Set myhostname = krbdev.mit.edu<br />
* Set mydestination = krbdev.mit.edu, krbdev-prod-app-1.mit.edu, localhost.mit.edu, localhost<br />
* Add the following to the end:<br />
<br />
# Suppress some headers to avoid leaking internal addresses to spammers.<br />
prepend_delivered_header =<br />
enable_original_recipient = no<br />
<br />
# RT header milter<br />
smtpd_milters = unix:private/milter<br />
<br />
Copy /etc/aliases from the old server. To avoid aiding spammers, its contents are not reproduced here. In particular, /etc/aliases contains an internal address corresponding to the membership of the krb5-bugs-incoming mailman list; revealing this address could allow spammers to bypass moderation of incoming bug reports.<br />
<br />
In root's crontab file ("crontab -e" as root):<br />
<br />
@reboot /var/rt2/bin/rtmilter.pl /var/spool/postfix/private/milter<br />
<br />
Run the command by hand (backgrounded) to start the milter process before the next reboot.<br />
<br />
Run "newaliases" and "postfix reload" to pick up the changed configuration.<br />
<br />
==Apache httpd configuration==<br />
<br />
Create /etc/apache2/ssl.crt and /etc/apache2/ssl.key.<br />
<br />
Copy /etc/apache2/ssl.key/server.key and /etc/apache2/ssl.crt/server.crt from the old server, or follow the instructions at http://kb.mit.edu/confluence/display/istcontrib/Obtaining+an+SSL+certificate+for+a+web+server to obtain a new one. server.key and server.crt may be symlinks using whatever scheme seems convenient for renewing certificates every few years.<br />
<br />
Install /etc/apache2/ssl.crt/chain.crt from /mit/apache-ssl/certificates/InCommon-chain.crt.txt (requires tokens). Cutting and pasting is effective for transferring certificates as they are represented as short text files.<br />
<br />
Install /etc/apache2/ssl.crt/clientCA.crt from /mit/apache-ssl/certificates/mitCAclient.pem (requires tokens).<br />
<br />
Install the rt.conf file from the krbdev-services repository as /etc/apache2/sites-available/rt.conf .<br />
<br />
Edit /etc/apache2/mods-available/proxy.conf and set:<br />
<br />
ProxyVia On<br />
<br />
ProxyPass /buildbot/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPassReverse /buildbos/ws ws://krbdev-buildbot.mit.edu:8010/ws<br />
ProxyPass /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
ProxyPassReverse /buildbot/ http://krbdev-buildbot.mit.edu:8010/<br />
<Proxy http://krbdev-buildbot.mit.edu:8010/*><br />
Allow from all<br />
</Proxy><br />
<br />
Clean out /var/www and install index.html and robots.txt from the krbdev-www directory of the krbdev-services repository.<br />
<br />
Run:<br />
<br />
a2enmod ssl<br />
a2enmod userdir<br />
a2enmod rewrite<br />
a2enmod proxy_http<br />
a2enmod proxy_wstunnel<br />
a2dissite 000-default<br />
a2ensite rt<br />
service apache2 restart</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Buildbot_server_configuration&diff=5997Buildbot server configuration2020-04-18T01:33:08Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 buildbot master and workers. The buildbot master is hosted on krbdev-buildbot.mit.edu. Workers are listed in machines.txt in the krbdev-services repository.<br />
<br />
==Operational notes==<br />
<br />
To force a new build on all workers, log into krbdev-buildbot.mit.edu, run "su -s /bin/bash - buildbot", then run "buildbot sendchange -b master -m localhost:9989 -W yourusername@mit.edu" (or similarly for a different branch).<br />
<br />
==Packages==<br />
<br />
The python3-buildbot package is required for the buildbot master. The git package is required for the krb5 repository mirror.<br />
<br />
Ubuntu 18.04 does not include the buildbot web interface, so it is necessary to install it using pip3:<br />
<br />
apt install python-pip3<br />
pip3 install buildbot-www buildbot-console-view buildbot-grid-view buildbot-waterfall-view<br />
<br />
==buildbot master setup==<br />
<br />
Run:<br />
<br />
su -s /bin/bash - buildbot<br />
touch .k5login<br />
rmdir masters workers<br />
buildbot create-master -r master<br />
<br />
Install buildbot/master.cfg from krbdev-services into /var/lib/buildbot/master. Copy /var/lib/buildbot/master/workers.py from the old server. Make sure both files are owned by and readable by buildbot. If it is necessary to reconstruct workers.py, has the form:<br />
<br />
from buildbot.worker import Worker<br />
workers = [<br />
Worker('v09', '<password>', properties={'platform': 'amd64-u1204'}),<br />
...<br />
]<br />
<br />
The name and password must match the values used on the worker. The platform is mostly arbitrary and will be used to construct builder entries. Multiple workers can have the same platform. The third argument may be omitted for workers that run special tasks (such as the documentation build) and aren't part of the regular platform builds.<br />
<br />
Copy over .ssh/authorized_keys from the old server's /var/lib/buildbot. If it is necessary to reconstruct it, it must contain the ssh key for each worker entry (.ssh/id_rsa.pub from the buildbot account on the worker).<br />
<br />
As root, edit /etc/default/buildmaster and change the values so they read:<br />
<br />
MASTER_ENABLED[1]=1<br />
MASTER_NAME[1]="master"<br />
MASTER_USER[1]="buildbot"<br />
MASTER_BASEDIR[1]="/var/lib/buildbot/master"<br />
MASTER_OPTIONS[1]=""<br />
MASTER_PREFIXCMD[1]=""<br />
<br />
Run "service buildmaster restart".<br />
<br />
Install a krbsnap keytab into /var/lib/buildbot, readable only by root. Install buildbot/doc-update.sh from krbdev-services into /var/lib/buildbot. Add the following cron job:<br />
<br />
0 4 * * * /var/lib/buildbot/doc-update.sh<br />
<br />
==git mirror setup==<br />
<br />
The buildbot master host runs a mirror of the drugstore krb5 git repository, for access by workers and to send change notifications to the buildbot master.<br />
<br />
Create a krbsnap account using the uid of the Athena krbsnap user:<br />
<br />
useradd -m -u 38160 -s /bin/bash krbsnap<br />
<br />
As krbsnap, create ~/.ssh and add the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu to ~/.ssh/authorized_keys. (This file may be managed by ops along with the .k5login file, and ops may have created the krbsnap account during provisioning.)<br />
<br />
As krbsnap, run:<br />
<br />
mkdir ~/krb5.git<br />
cd ~/krb5.git<br />
git init --bare<br />
<br />
To populate the git repository, log into drugstore as root, "su -s /bin/bash - yourusername", and run:<br />
<br />
cd /git/krb5.git<br />
GIT_SSH=/git/krb5.git/hooks/ssh-as-krbsnap git push krbsnap<br />
<br />
Make sure that /git/krb5.git/config contains a remote named "krbsnap" for krbsnap@krbdev-buildbot.mit.edu, and that the [hooks] section contains an entry "push-to = krbsnap".<br />
<br />
As krbsnap, fetch the git_buildbot.py script ( https://raw.githubusercontent.com/buildbot/buildbot-contrib/master/master/contrib/git_buildbot.py ) into ~/krb5.git/hooks, and modify it to begin with "#!/usr/bin/python3". Make sure it is executable. Run:<br />
<br />
cd ~/krb5.git<br />
touch git-daemon-export-ok<br />
cd hooks<br />
ln -s git_buildbot.py post-receive<br />
<br />
As krbsnap, run "crontab -e" and add this entry:<br />
<br />
@reboot git daemon --detach --base-path=$HOME<br />
<br />
Run the command by hand to start the daemon initially.<br />
<br />
==buildbot worker setup==<br />
<br />
For the Solaris buildbot worker, see [[Solaris_Build_Environment]] for platform-specific instructions.<br />
<br />
Install the buildbot worker software, using the python3-buildbot-worker package (buildbot-slave prior to Ubuntu 18.04) or the platform equivalent.<br />
<br />
Install the following Ubuntu packages: autoconf bison build-essential dejagnu git keyutils ldap-utils libcmocka-dev libkeyutils-dev libldap2-dev liblmdb-dev libsasl2-dev libssl-dev libtool pkg-config python3-kdcproxy python3-pip tcl-dev<br />
<br />
Install the slapd package. apt may ask for a master password twice; the value is unimportant and can be left blank.<br />
<br />
On Ubuntu 18.04 or later, install libresolv-wrapper.<br />
<br />
Run "pip3 install pyrad".<br />
<br />
(TBD: enumerate packages needed for documentation build worker.)<br />
<br />
If the platform package does not create a buildbot account, create one with a home directory. Create an empty .k5login file in the buildbot home directory. These instructions will assume that the buildbot home directory is /var/lib/buildbot.<br />
<br />
As the buildbot account ("su -s /bin/bash - buildbot"), generate a key using:<br />
<br />
ssh-keygen -q -N '' -f .ssh/id_rsa -t rsa<br />
<br />
Add the contents of .ssh/id_rsa.pub to ~buildbot/.ssh/authorized_keys on krbdev-buildbot.mit.edu.<br />
<br />
Run "ssh -l buildbot krbdev-buildbot.mit.edu" to get the master host key into .ssh/known_hosts. The correct host key fingerprint of the master can be obtained by running "ssh-keygen -l -E sha256 -f /etc/ssh/ssh_host_ecdsa_key.pub" on krbdev-buildbot.mit.edu (or perhaps ssh_host_rsa_key.pub or ssh_host_dsa_key.pub if the worker has an old ssh client).<br />
<br />
Create a "workers" directory in buildbot's home directory and run "buildbot-worker create-worker /var/lib/buildbot/workers/NAME 127.0.0.1:9989 NAME PASSWORD", using the name and password from the slaves.py entry for the worker. Prior to Ubuntu 18.04, the command is "buildslave create-slave" and the subdirectory should be named "slaves".<br />
<br />
Arrange for the buildslave process to be started on boot. On Ubuntu 18.04, this is accomplished by editing /etc/default/buildbot-worker as root and setting:<br />
<br />
WORKER_ENABLED[1]=1<br />
WORKER_NAME[1]="NAME"<br />
WORKER_USER[1]="buildbot"<br />
WORKER_BASEDIR[1]="/var/lib/buildbot/workers/NAME"<br />
WORKER_OPTIONS[1]=""<br />
WORKER_PREFIXCMD[1]=""<br />
<br />
On earlier versions of Ubuntu, the file is /etc/default/buildslave and each occurrence of "worker" is replaced with "slave".<br />
<br />
Add a cron job for the buildbot account (run "crontab -e" as buildbot) to maintain the ssh tunnel to the master:<br />
<br />
*/5 * * * * exec ssh -oExitOnForwardFailure=yes -l buildbot -N -L9989:127.0.0.1:9989 krbdev-buildbot.mit.edu<br />
<br />
Run the command manually (backgrounded, without the "exec") to start it for the current session.<br />
<br />
The worker which runs the documentation build needs the python3-lxml package, and either the python3-cheetah package (requires Ubuntu 18.10 or higher) or the python3-pip package and "pip3 install cheetah3" to be run.<br />
<br />
==snapshot service==<br />
<br />
This service is probably no longer needed, but the setup details are covered here in case it becomes necessary to resurrect it.<br />
<br />
In the krbsnap home directory, create a subdirectory "snap" and copy the krbdev/gensnap script from krbdev-services into it. Also create a keytab for the krbsnap principal in ~/snap/krbsnap.keytab. Add the cron job to run gensnap from krbdev/krbsnap-crontab to the crontab for the krbsnap account. (Do not install sync_gitsvn or its cron job; it is defunct.)<br />
<br />
The gensnap script updates a working copy for each branch, runs mkrel, and installs the results in krbsnap@aeneas.mit.edu:/var/ftp/pub/kerberos/dist/vaporware-r-us . These snapshots are used by the old nightly build infrastructure (scripts in /mit/krbdev/testing), which has been supplanted by other CI systems.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Buildbot_server_configuration&diff=5996Buildbot server configuration2020-04-18T01:16:59Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 buildbot master and workers. The buildbot master is hosted on krbdev-buildbot.mit.edu. Workers are listed in machines.txt in the krbdev-services repository.<br />
<br />
==Operational notes==<br />
<br />
To force a new build on all workers, log into krbdev-buildbot.mit.edu, run "su -s /bin/bash - buildbot", then run "buildbot sendchange -b master -m localhost:9989 -W yourusername@mit.edu" (or similarly for a different branch).<br />
<br />
==Packages==<br />
<br />
The buildbot package is required for the buildbot master. The git package is required for the krb5 repository mirror.<br />
<br />
==buildbot master setup==<br />
<br />
buildbot 0.9 changes its terminology to refer to "workers" rather than "slaves". At the current time the buildbot server runs on Ubuntu 16.04, where the buildbot package is version 0.8.12. These notes will need to be updated when we move to 0.9 or later.<br />
<br />
Run:<br />
<br />
su -s /bin/bash - buildbot<br />
touch .k5login<br />
rmdir masters slaves<br />
buildbot create-master -r master<br />
<br />
Install buildbot/master.cfg from krbdev-services into /var/lib/buildbot/master. Copy /var/lib/buildbot/master/slaves.py from the old server. Make sure both files are owned by and readable by buildbot. If it is necessary to reconstruct slaves.py, has the form:<br />
<br />
from buildbot.buildslave import BuildSlave<br />
slaves = [<br />
BuildSlave('v09', '<password>', properties={'platform': 'amd64-u1204'}),<br />
...<br />
]<br />
<br />
The name and password must match the values used on the worker. The platform is mostly arbitrary and will be used to construct builder entries. Multiple workers can have the same platform. The third argument may be omitted for workers which run special tasks (such as the documentation build) which aren't part of the regular platform builds.<br />
<br />
Copy over .ssh/authorized_keys from the old server's /var/lib/buildbot. If it is necessary to reconstruct it, it must contain the ssh key for each worker entry (.ssh/id_rsa.pub from the buildbot account on the worker).<br />
<br />
As root, edit /etc/default/buildmaster and change the values so they read:<br />
<br />
MASTER_ENABLED[1]=1<br />
MASTER_NAME[1]="master"<br />
MASTER_USER[1]="buildbot"<br />
MASTER_BASEDIR[1]="/var/lib/buildbot/master"<br />
MASTER_OPTIONS[1]=""<br />
MASTER_PREFIXCMD[1]=""<br />
<br />
Run "service buildmaster restart".<br />
<br />
Install a krbsnap keytab into /var/lib/buildbot, readable only by root. Install buildbot/doc-update.sh from krbdev-services into /var/lib/buildbot. Add the following cron job:<br />
<br />
0 4 * * * /var/lib/buildbot/doc-update.sh<br />
<br />
==git mirror setup==<br />
<br />
The buildbot master host runs a mirror of the drugstore krb5 git repository, for access by workers and to send change notifications to the buildbot master.<br />
<br />
Create a krbsnap account using the uid of the Athena krbsnap user:<br />
<br />
useradd -m -u 38160 -s /bin/bash krbsnap<br />
<br />
As krbsnap, create ~/.ssh and add the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu to ~/.ssh/authorized_keys. (This file may be managed by ops along with the .k5login file, and ops may have created the krbsnap account during provisioning.)<br />
<br />
As krbsnap, run:<br />
<br />
mkdir ~/krb5.git<br />
cd ~/krb5.git<br />
git init --bare<br />
<br />
To populate the git repository, log into drugstore as root, "su -s /bin/bash - yourusername", and run:<br />
<br />
cd /git/krb5.git<br />
GIT_SSH=/git/krb5.git/hooks/ssh-as-krbsnap git push krbsnap<br />
<br />
Make sure that /git/krb5.git/config contains a remote named "krbsnap" for krbsnap@krbdev-buildbot.mit.edu, and that the [hooks] section contains an entry "push-to = krbsnap".<br />
<br />
As krbsnap, run:<br />
<br />
cd ~/krb5.git<br />
touch git-daemon-export-ok<br />
cd hooks<br />
cp /usr/share/buildbot/contrib/git_buildbot.py .<br />
ln -s git_buildbot.py post-receive<br />
<br />
As krbsnap, run "crontab -e" and add this entry:<br />
<br />
@reboot git daemon --detach --base-path=$HOME<br />
<br />
Run the command by hand to start the daemon initially.<br />
<br />
==buildbot worker setup==<br />
<br />
For the Solaris buildbot worker, see [[Solaris_Build_Environment]] for platform-specific instructions.<br />
<br />
Install the buildbot worker software, using the python3-buildbot-worker package (buildbot-slave prior to Ubuntu 18.04) or the platform equivalent.<br />
<br />
Install the following Ubuntu packages: autoconf bison build-essential dejagnu git keyutils ldap-utils libcmocka-dev libkeyutils-dev libldap2-dev liblmdb-dev libsasl2-dev libssl-dev libtool pkg-config python3-kdcproxy python3-pip tcl-dev<br />
<br />
Install the slapd package. apt may ask for a master password twice; the value is unimportant and can be left blank.<br />
<br />
On Ubuntu 18.04 or later, install libresolv-wrapper.<br />
<br />
Run "pip3 install pyrad".<br />
<br />
(TBD: enumerate packages needed for documentation build worker.)<br />
<br />
If the platform package does not create a buildbot account, create one with a home directory. Create an empty .k5login file in the buildbot home directory. These instructions will assume that the buildbot home directory is /var/lib/buildbot.<br />
<br />
As the buildbot account ("su -s /bin/bash - buildbot"), generate a key using:<br />
<br />
ssh-keygen -q -N '' -f .ssh/id_rsa -t rsa<br />
<br />
Add the contents of .ssh/id_rsa.pub to ~buildbot/.ssh/authorized_keys on krbdev-buildbot.mit.edu.<br />
<br />
Run "ssh -l buildbot krbdev-buildbot.mit.edu" to get the master host key into .ssh/known_hosts. The correct host key fingerprint of the master can be obtained by running "ssh-keygen -l -E sha256 -f /etc/ssh/ssh_host_ecdsa_key.pub" on krbdev-buildbot.mit.edu (or perhaps ssh_host_rsa_key.pub or ssh_host_dsa_key.pub if the worker has an old ssh client).<br />
<br />
Create a "workers" directory in buildbot's home directory and run "buildbot-worker create-worker /var/lib/buildbot/workers/NAME 127.0.0.1:9989 NAME PASSWORD", using the name and password from the slaves.py entry for the worker. Prior to Ubuntu 18.04, the command is "buildslave create-slave" and the subdirectory should be named "slaves".<br />
<br />
Arrange for the buildslave process to be started on boot. On Ubuntu 18.04, this is accomplished by editing /etc/default/buildbot-worker as root and setting:<br />
<br />
WORKER_ENABLED[1]=1<br />
WORKER_NAME[1]="NAME"<br />
WORKER_USER[1]="buildbot"<br />
WORKER_BASEDIR[1]="/var/lib/buildbot/workers/NAME"<br />
WORKER_OPTIONS[1]=""<br />
WORKER_PREFIXCMD[1]=""<br />
<br />
On earlier versions of Ubuntu, the file is /etc/default/buildslave and each occurrence of "worker" is replaced with "slave".<br />
<br />
Add a cron job for the buildbot account (run "crontab -e" as buildbot) to maintain the ssh tunnel to the master:<br />
<br />
*/5 * * * * exec ssh -oExitOnForwardFailure=yes -l buildbot -N -L9989:127.0.0.1:9989 krbdev-buildbot.mit.edu<br />
<br />
Run the command manually (backgrounded, without the "exec") to start it for the current session.<br />
<br />
The worker which runs the documentation build needs the python3-lxml package, and either the python3-cheetah package (requires Ubuntu 18.10 or higher) or the python3-pip package and "pip3 install cheetah3" to be run.<br />
<br />
==snapshot service==<br />
<br />
This service is probably no longer needed, but the setup details are covered here in case it becomes necessary to resurrect it.<br />
<br />
In the krbsnap home directory, create a subdirectory "snap" and copy the krbdev/gensnap script from krbdev-services into it. Also create a keytab for the krbsnap principal in ~/snap/krbsnap.keytab. Add the cron job to run gensnap from krbdev/krbsnap-crontab to the crontab for the krbsnap account. (Do not install sync_gitsvn or its cron job; it is defunct.)<br />
<br />
The gensnap script updates a working copy for each branch, runs mkrel, and installs the results in krbsnap@aeneas.mit.edu:/var/ftp/pub/kerberos/dist/vaporware-r-us . These snapshots are used by the old nightly build infrastructure (scripts in /mit/krbdev/testing), which has been supplanted by other CI systems.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Buildbot_server_configuration&diff=5995Buildbot server configuration2020-04-18T01:15:22Z<p>Ghudson: </p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 buildbot master and workers. The buildbot master is hosted on krbdev-buildbot.mit.edu. Workers are listed in machines.txt in the krbdev-services repository.<br />
<br />
==Operational notes==<br />
<br />
To force a new build on all workers, log into krbdev-buildbot.mit.edu, run "su -s /bin/bash - buildbot", then run "buildbot sendchange -b master -m localhost:9989 -W yourusername@mit.edu" (or similarly for a different branch).<br />
<br />
==Packages==<br />
<br />
The buildbot package is required for the buildbot master. The git package is required for the krb5 repository mirror.<br />
<br />
==buildbot master setup==<br />
<br />
buildbot 0.9 changes its terminology to refer to "workers" rather than "slaves". At the current time the buildbot server runs on Ubuntu 16.04, where the buildbot package is version 0.8.12. These notes will need to be updated when we move to 0.9 or later.<br />
<br />
Run:<br />
<br />
su -s /bin/bash - buildbot<br />
touch .k5login<br />
rmdir masters slaves<br />
buildbot create-master -r master<br />
<br />
Install buildbot/master.cfg from krbdev-services into /var/lib/buildbot/master. Copy /var/lib/buildbot/master/slaves.py from the old server. Make sure both files are owned by and readable by buildbot. If it is necessary to reconstruct slaves.py, has the form:<br />
<br />
from buildbot.buildslave import BuildSlave<br />
slaves = [<br />
BuildSlave('v09', '<password>', properties={'platform': 'amd64-u1204'}),<br />
...<br />
]<br />
<br />
The name and password must match the values used on the worker. The platform is mostly arbitrary and will be used to construct builder entries. Multiple workers can have the same platform. The third argument may be omitted for workers which run special tasks (such as the documentation build) which aren't part of the regular platform builds.<br />
<br />
Copy over .ssh/authorized_keys from the old server's /var/lib/buildbot. If it is necessary to reconstruct it, it must contain the ssh key for each worker entry (.ssh/id_rsa.pub from the buildbot account on the worker).<br />
<br />
As root, edit /etc/default/buildmaster and change the values so they read:<br />
<br />
MASTER_ENABLED[1]=1<br />
MASTER_NAME[1]="master"<br />
MASTER_USER[1]="buildbot"<br />
MASTER_BASEDIR[1]="/var/lib/buildbot/master"<br />
MASTER_OPTIONS[1]=""<br />
MASTER_PREFIXCMD[1]=""<br />
<br />
Run "service buildmaster restart".<br />
<br />
Install a krbsnap keytab into /var/lib/buildbot, readable only by root. Install buildbot/doc-update.sh from krbdev-services into /var/lib/buildbot. Add the following cron job:<br />
<br />
0 4 * * * /var/lib/buildbot/doc-update.sh<br />
<br />
==git mirror setup==<br />
<br />
The buildbot master host runs a mirror of the drugstore krb5 git repository, for access by workers and to send change notifications to the buildbot master.<br />
<br />
Create a krbsnap account using the uid of the Athena krbsnap user:<br />
<br />
useradd -m -u 38160 -s /bin/bash krbsnap<br />
<br />
As krbsnap, create ~/.ssh and add the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu to ~/.ssh/authorized_keys. (This file may be managed by ops along with the .k5login file, and ops may have created the krbsnap account during provisioning.)<br />
<br />
As krbsnap, run:<br />
<br />
mkdir ~/krb5.git<br />
cd ~/krb5.git<br />
git init --bare<br />
<br />
To populate the git repository, log into drugstore as root, "su -s /bin/bash - yourusername", and run:<br />
<br />
cd /git/krb5.git<br />
GIT_SSH=/git/krb5.git/hooks/ssh-as-krbsnap git push krbsnap<br />
<br />
Make sure that /git/krb5.git/config contains a remote named "krbsnap" for krbsnap@krbdev-buildbot.mit.edu, and that the [hooks] section contains an entry "push-to = krbsnap".<br />
<br />
As krbsnap, run:<br />
<br />
cd ~/krb5.git<br />
touch git-daemon-export-ok<br />
cd hooks<br />
cp /usr/share/buildbot/contrib/git_buildbot.py .<br />
ln -s git_buildbot.py post-receive<br />
<br />
As krbsnap, run "crontab -e" and add this entry:<br />
<br />
@reboot git daemon --detach --base-path=$HOME<br />
<br />
Run the command by hand to start the daemon initially.<br />
<br />
==buildbot worker setup==<br />
<br />
For the Solaris buildbot worker, see [[Solaris_Build_Environment]] for platform-specific instructions.<br />
<br />
Install the buildbot worker software, using the python3-buildbot-worker package (buildbot-slave prior to Ubuntu 18.04) or the platform equivalent.<br />
<br />
Install the following Ubuntu packages: autoconf bison build-essential dejagnu keyutils ldap-utils libcmocka-dev libkeyutils-dev libldap2-dev liblmdb-dev libsasl2-dev libssl-dev libtool pkg-config python3-kdcproxy python3-pip tcl-dev<br />
<br />
Install the slapd package. apt may ask for a master password twice; the value is unimportant and can be left blank.<br />
<br />
On Ubuntu 18.04 or later, install libresolv-wrapper.<br />
<br />
Run "pip3 install pyrad".<br />
<br />
(TBD: enumerate packages needed for documentation build worker.)<br />
<br />
If the platform package does not create a buildbot account, create one with a home directory. Create an empty .k5login file in the buildbot home directory. These instructions will assume that the buildbot home directory is /var/lib/buildbot.<br />
<br />
As the buildbot account ("su -s /bin/bash - buildbot"), generate a key using:<br />
<br />
ssh-keygen -q -N '' -f .ssh/id_rsa -t rsa<br />
<br />
Add the contents of .ssh/id_rsa.pub to ~buildbot/.ssh/authorized_keys on krbdev-buildbot.mit.edu.<br />
<br />
Run "ssh -l buildbot krbdev-buildbot.mit.edu" to get the master host key into .ssh/known_hosts. The correct host key fingerprint of the master can be obtained by running "ssh-keygen -l -E sha256 -f /etc/ssh/ssh_host_ecdsa_key.pub" on krbdev-buildbot.mit.edu (or perhaps ssh_host_rsa_key.pub or ssh_host_dsa_key.pub if the worker has an old ssh client).<br />
<br />
Create a "workers" directory in buildbot's home directory and run "buildbot-worker create-worker /var/lib/buildbot/workers/NAME 127.0.0.1:9989 NAME PASSWORD", using the name and password from the slaves.py entry for the worker. Prior to Ubuntu 18.04, the command is "buildslave create-slave" and the subdirectory should be named "slaves".<br />
<br />
Arrange for the buildslave process to be started on boot. On Ubuntu 18.04, this is accomplished by editing /etc/default/buildbot-worker as root and setting:<br />
<br />
WORKER_ENABLED[1]=1<br />
WORKER_NAME[1]="NAME"<br />
WORKER_USER[1]="buildbot"<br />
WORKER_BASEDIR[1]="/var/lib/buildbot/workers/NAME"<br />
WORKER_OPTIONS[1]=""<br />
WORKER_PREFIXCMD[1]=""<br />
<br />
On earlier versions of Ubuntu, the file is /etc/default/buildslave and each occurrence of "worker" is replaced with "slave".<br />
<br />
Add a cron job for the buildbot account (run "crontab -e" as buildbot) to maintain the ssh tunnel to the master:<br />
<br />
*/5 * * * * exec ssh -oExitOnForwardFailure=yes -l buildbot -N -L9989:127.0.0.1:9989 krbdev-buildbot.mit.edu<br />
<br />
Run the command manually (backgrounded, without the "exec") to start it for the current session.<br />
<br />
The worker which runs the documentation build needs the python3-lxml package, and either the python3-cheetah package (requires Ubuntu 18.10 or higher) or the python3-pip package and "pip3 install cheetah3" to be run.<br />
<br />
==snapshot service==<br />
<br />
This service is probably no longer needed, but the setup details are covered here in case it becomes necessary to resurrect it.<br />
<br />
In the krbsnap home directory, create a subdirectory "snap" and copy the krbdev/gensnap script from krbdev-services into it. Also create a keytab for the krbsnap principal in ~/snap/krbsnap.keytab. Add the cron job to run gensnap from krbdev/krbsnap-crontab to the crontab for the krbsnap account. (Do not install sync_gitsvn or its cron job; it is defunct.)<br />
<br />
The gensnap script updates a working copy for each branch, runs mkrel, and installs the results in krbsnap@aeneas.mit.edu:/var/ftp/pub/kerberos/dist/vaporware-r-us . These snapshots are used by the old nightly build infrastructure (scripts in /mit/krbdev/testing), which has been supplanted by other CI systems.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Buildbot_server_configuration&diff=5994Buildbot server configuration2020-04-15T23:34:42Z<p>Ghudson: /* buildbot worker setup */</p>
<hr />
<div>This page contains notes on the setup of the MIT krb5 buildbot master and workers. The buildbot master is hosted on krbdev-buildbot.mit.edu. Workers are listed in machines.txt in the krbdev-services repository.<br />
<br />
==Operational notes==<br />
<br />
To force a new build on all workers, log into krbdev-buildbot.mit.edu, run "su -s /bin/bash - buildbot", then run "buildbot sendchange -b master -m localhost:9989 -W yourusername@mit.edu" (or similarly for a different branch).<br />
<br />
==Packages==<br />
<br />
The buildbot package is required for the buildbot master. The git package is required for the krb5 repository mirror.<br />
<br />
==buildbot master setup==<br />
<br />
buildbot 0.9 changes its terminology to refer to "workers" rather than "slaves". At the current time the buildbot server runs on Ubuntu 16.04, where the buildbot package is version 0.8.12. These notes will need to be updated when we move to 0.9 or later.<br />
<br />
Run:<br />
<br />
su -s /bin/bash - buildbot<br />
touch .k5login<br />
rmdir masters slaves<br />
buildbot create-master -r master<br />
<br />
Install buildbot/master.cfg from krbdev-services into /var/lib/buildbot/master. Copy /var/lib/buildbot/master/slaves.py from the old server. Make sure both files are owned by and readable by buildbot. If it is necessary to reconstruct slaves.py, has the form:<br />
<br />
from buildbot.buildslave import BuildSlave<br />
slaves = [<br />
BuildSlave('v09', '<password>', properties={'platform': 'amd64-u1204'}),<br />
...<br />
]<br />
<br />
The name and password must match the values used on the worker. The platform is mostly arbitrary and will be used to construct builder entries. Multiple workers can have the same platform. The third argument may be omitted for workers which run special tasks (such as the documentation build) which aren't part of the regular platform builds.<br />
<br />
Copy over .ssh/authorized_keys from the old server's /var/lib/buildbot. If it is necessary to reconstruct it, it must contain the ssh key for each worker entry (.ssh/id_rsa.pub from the buildbot account on the worker).<br />
<br />
As root, edit /etc/default/buildmaster and change the values so they read:<br />
<br />
MASTER_ENABLED[1]=1<br />
MASTER_NAME[1]="master"<br />
MASTER_USER[1]="buildbot"<br />
MASTER_BASEDIR[1]="/var/lib/buildbot/master"<br />
MASTER_OPTIONS[1]=""<br />
MASTER_PREFIXCMD[1]=""<br />
<br />
Run "service buildmaster restart".<br />
<br />
Install a krbsnap keytab into /var/lib/buildbot, readable only by root. Install buildbot/doc-update.sh from krbdev-services into /var/lib/buildbot. Add the following cron job:<br />
<br />
0 4 * * * /var/lib/buildbot/doc-update.sh<br />
<br />
==git mirror setup==<br />
<br />
The buildbot master host runs a mirror of the drugstore krb5 git repository, for access by workers and to send change notifications to the buildbot master.<br />
<br />
Create a krbsnap account using the uid of the Athena krbsnap user:<br />
<br />
useradd -m -u 38160 -s /bin/bash krbsnap<br />
<br />
As krbsnap, create ~/.ssh and add the krbsnap key from /git/krb5.git/hooks/krbsnap_rsa_key.pub on drugstore.mit.edu to ~/.ssh/authorized_keys. (This file may be managed by ops along with the .k5login file, and ops may have created the krbsnap account during provisioning.)<br />
<br />
As krbsnap, run:<br />
<br />
mkdir ~/krb5.git<br />
cd ~/krb5.git<br />
git init --bare<br />
<br />
To populate the git repository, log into drugstore as root, "su -s /bin/bash - yourusername", and run:<br />
<br />
cd /git/krb5.git<br />
GIT_SSH=/git/krb5.git/hooks/ssh-as-krbsnap git push krbsnap<br />
<br />
Make sure that /git/krb5.git/config contains a remote named "krbsnap" for krbsnap@krbdev-buildbot.mit.edu, and that the [hooks] section contains an entry "push-to = krbsnap".<br />
<br />
As krbsnap, run:<br />
<br />
cd ~/krb5.git<br />
touch git-daemon-export-ok<br />
cd hooks<br />
cp /usr/share/buildbot/contrib/git_buildbot.py .<br />
ln -s git_buildbot.py post-receive<br />
<br />
As krbsnap, run "crontab -e" and add this entry:<br />
<br />
@reboot git daemon --detach --base-path=$HOME<br />
<br />
Run the command by hand to start the daemon initially.<br />
<br />
==buildbot worker setup==<br />
<br />
For the Solaris buildbot worker, see [[Solaris_Build_Environment]] for platform-specific instructions.<br />
<br />
Install the buildbot worker software, using the python3-buildbot-worker package (buildbot-slave prior to Ubuntu 18.04) or the platform equivalent.<br />
<br />
Install the following Ubuntu packages: autoconf bison build-essential dejagnu keyutils ldap-utils libcmocka-dev libkeyutils-dev libldap2-dev liblmdb-dev libsasl2-dev libssl-dev libtool pkg-config python3-kdcproxy python3-pip tcl-dev<br />
<br />
Install the slapd package. apt may ask for a master password twice; the value is unimportant and can be left blank.<br />
<br />
On Ubuntu 18.04 or later, install libresolv-wrapper.<br />
<br />
Run "pip3 install pyrad".<br />
<br />
If the platform package does not create a buildbot account, create one with a home directory. Create an empty .k5login file in the buildbot home directory. These instructions will assume that the buildbot home directory is /var/lib/buildbot.<br />
<br />
As the buildbot account ("su -s /bin/bash - buildbot"), generate a key using:<br />
<br />
ssh-keygen -q -N '' -f .ssh/id_rsa -t rsa<br />
<br />
Add the contents of .ssh/id_rsa.pub to ~buildbot/.ssh/authorized_keys on krbdev-buildbot.mit.edu.<br />
<br />
Run "ssh -l buildbot krbdev-buildbot.mit.edu" to get the master host key into .ssh/known_hosts. The correct host key fingerprint of the master can be obtained by running "ssh-keygen -l -E sha256 -f /etc/ssh/ssh_host_ecdsa_key.pub" on krbdev-buildbot.mit.edu (or perhaps ssh_host_rsa_key.pub or ssh_host_dsa_key.pub if the worker has an old ssh client).<br />
<br />
Create a "workers" directory in buildbot's home directory and run "buildbot-worker create-worker /var/lib/buildbot/workers/NAME 127.0.0.1:9989 NAME PASSWORD", using the name and password from the slaves.py entry for the worker. Prior to Ubuntu 18.04, the command is "buildslave create-slave" and the subdirectory should be named "slaves".<br />
<br />
Arrange for the buildslave process to be started on boot. On Ubuntu 18.04, this is accomplished by editing /etc/default/buildbot-worker as root and setting:<br />
<br />
WORKER_ENABLED[1]=1<br />
WORKER_NAME[1]="NAME"<br />
WORKER_USER[1]="buildbot"<br />
WORKER_BASEDIR[1]="/var/lib/buildbot/workers/NAME"<br />
WORKER_OPTIONS[1]=""<br />
WORKER_PREFIXCMD[1]=""<br />
<br />
On earlier versions of Ubuntu, the file is /etc/default/buildslave and each occurrence of "worker" is replaced with "slave".<br />
<br />
Add a cron job for the buildbot account (run "crontab -e" as buildbot) to maintain the ssh tunnel to the master:<br />
<br />
*/5 * * * * exec ssh -oExitOnForwardFailure=yes -l buildbot -N -L9989:127.0.0.1:9989 krbdev-buildbot.mit.edu<br />
<br />
Run the command manually (backgrounded, without the "exec") to start it for the current session.<br />
<br />
The worker which runs the documentation build needs the python3-lxml package, and either the python3-cheetah package (requires Ubuntu 18.10 or higher) or the python3-pip package and "pip3 install cheetah3" to be run.<br />
<br />
==snapshot service==<br />
<br />
This service is probably no longer needed, but the setup details are covered here in case it becomes necessary to resurrect it.<br />
<br />
In the krbsnap home directory, create a subdirectory "snap" and copy the krbdev/gensnap script from krbdev-services into it. Also create a keytab for the krbsnap principal in ~/snap/krbsnap.keytab. Add the cron job to run gensnap from krbdev/krbsnap-crontab to the crontab for the krbsnap account. (Do not install sync_gitsvn or its cron job; it is defunct.)<br />
<br />
The gensnap script updates a working copy for each branch, runs mkrel, and installs the results in krbsnap@aeneas.mit.edu:/var/ftp/pub/kerberos/dist/vaporware-r-us . These snapshots are used by the old nightly build infrastructure (scripts in /mit/krbdev/testing), which has been supplanted by other CI systems.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Debugging_tips&diff=5993Debugging tips2020-04-14T22:22:50Z<p>Ghudson: </p>
<hr />
<div>[[Category:Lore]]<br />
This page documents krb5-specific techniques which may help debug problems. Feel free to add additional techniques.<br />
<br />
As always, the basic tools are helpful: debuggers like gdb or dbx, system call tracing tools like strace or truss, shared library tracing tools like ltrace or sotruss, and memory debugging tools like valgrind or Purify.<br />
<br />
==Building for Testing or Debugging ==<br />
<br />
By default, krb5 will build with optimization, making it difficult to debug. You can change this at configure time using the CFLAGS variable:<br />
<br />
.../configure CFLAGS=-g<br />
<br />
or at build time:<br />
<br />
make CFLAGS=-g<br />
<br />
C++ code uses CXXFLAGS instead of CFLAGS. There isn't a lot of C++ code in the Unix build, but if you do run into a need to debug what there is, be sure to override CXXFLAGS as well as CFLAGS.<br />
<br />
On some platforms, programs built with run-path options will consult the run path before LD_LIBRARY_PATH. (This is less of a concern than it used to be because we now build with -Wl,--enable-new-dtags on Linux and FreeBSD, which causes the generated binaries to prefer LD_LIBRARY_PATH to the run path.) On these platforms, libraries from the install prefix will take precedence over libraries in the build tree. This is particularly important to know when running the test suite. To work around this issue, you can "make install" before "make check", or you can configure the tree to build without run-path options:<br />
<br />
.../configure --disable-rpath<br />
<br />
A tree built this way may not be as useful when installed (since the binaries won't know how to find the libraries), but is more convenient for running programs out of the build tree. Note that plugins will still be loaded from the install prefix by default. The test suite overrides the plugin paths using special krb5.conf directives; if you are running a program by hand from the build tree and it uses plugins, you must either do the same overriding or run "make install" before running the program.<br />
<br />
If you are using certain kinds of instrumentation (such as gcov), you might need to do a build with static instead of shared libraries. You can do this with the --enable-static --disable-shared configuration flags. This flag will cause in-tree KDB plugins to be linked statically to the KDB library instead of loaded dynamically. At the moment, other kinds of plugins (such as preauth plugins) simply won't function.<br />
<br />
==Trace Logging==<br />
<br />
Even with a regular production build (for krb5 1.9 or trunk code after 2010-06-07), you can display trace events by setting the KRB5_TRACE environment variable to a filename. For example, try "env KRB5_TRACE=/dev/stdout kinit" to see some behind-the-scenes information about getting initial credentials. The KRB5_TRACE environment variable will not work for secure contexts, such as those created by ksu or login systems.<br />
<br />
==Compile-Time Defines==<br />
<br />
You can specify extra defined symbols for the build at configure time like so:<br />
<br />
.../configure CPPFLAGS=-DFLAGNAME<br />
<br />
or at build time:<br />
<br />
make CPPFLAGS=-DFLAGNAME<br />
<br />
=== -DDEBUG ===<br />
<br />
Running<br />
<br />
make CPPFLAGS=-DDEBUG<br />
<br />
from the top of the build tree or<br />
<br />
.../configure CPPFLAGS=-DDEBUG<br />
<br />
is not recommended. Some code under <code>-DDEBUG</code> will not compile or link successfully. It is better to run<br />
<br />
make CPPFLAGS=-DDEBUG<br />
<br />
in a single subdirectory containing the code of interest.<br />
<br />
==Debugging the KDC==<br />
<br />
krb5kdc can be run with the -n flag to prevent it from backgrounding itself, allowing you to set breakpoints before it starts. Alternatively, you can attach to the process after it forks. The process_as_req and process_tgs_req functions are the entry points to handling client requests.<br />
<br />
==Using gcov for code coverage measurements==<br />
<br />
gcov is a gcc-based tool for computing code coverage. It can be used to determine the code coverage of the test suite, or to aid in debugging by showing what areas of code are executed during a manual test. If you are running an older operating system release, you may need a newer version of gcc in order to use gcov with shared libraries.<br />
<br />
* Configure with CFLAGS="-g --coverage" LDFLAGS="--coverage". Building with these flags will create .gcno files in your build tree.<br />
* Run whatever programs you want to compute coverage of. Running programs will create .gcda files in your build tree.<br />
* cd into a subdirectory and run "gcov -f filename.c -o filename.so.gcov" to see the code coverage of that source file. (If the build directory is not the source directory, specify the full path to the source file.) gcov will display the percentage coverage of each function in its output, and will also create filename.c.gcov showing the number of times each line of code was executed. Note that static inline functions in our header files will be reported in each source file which includes those headers, artificially reducing the apparent coverage.<br />
* Note that coverage data is only written when a program exits normally. If the program exits due to an unhandled signal, coverage information from that run will be lost.</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=5992Release engineering notes2019-12-11T17:54:21Z<p>Ghudson: /* Post-mkrel */</p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y" and push to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1).<br />
** In README, copy the list of contributors from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code> (only for minor releases, not patch releases)<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudsonhttps://k5wiki.kerberos.org/wiki?title=Release_engineering_notes&diff=5991Release engineering notes2019-12-11T16:38:01Z<p>Ghudson: /* Creating a new release branch */</p>
<hr />
<div>==Release engineering environment==<br />
<br />
Release engineering operations are currently performed on a Ubuntu 18.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.<br />
<br />
The release engineering host must have the following packages installed:<br />
<br />
* autoconf<br />
* bison<br />
* build-essential<br />
* dejagnu<br />
* doxygen<br />
* flex<br />
* git<br />
* keyutils<br />
* ldap-utils<br />
* libcmocka-dev<br />
* libkeyutils-dev<br />
* libldap2-dev<br />
* liblmdb-dev<br />
* libresolv-wrapper<br />
* libsasl2-dev<br />
* libssl-dev<br />
* libtool<br />
* pkg-config<br />
* python-sphinx<br />
* python-cheetah<br />
* rcs<br />
* slapd<br />
* tcl-dev<br />
* texlive<br />
* texlive-latex-extra<br />
<br />
==Pulling up changes to release branches==<br />
<br />
* For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.<br />
<br />
* Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.<br />
<br />
* If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.<br />
<br />
* For each release branch:<br />
** For each ticket marked for pullup to that branch:<br />
*** For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch.<br />
*** Examine the commits any consider any possible interactions with changes made since the release branch.<br />
*** Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.<br />
*** If the change isn't covered by automated tests, consider testing it by hand.<br />
* Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.<br />
* If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.<br />
* Push the updated release branches to the authoritative repository.<br />
* Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.<br />
<br />
==Creating a new release branch==<br />
<br />
* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.<br />
* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:<br />
** Queue is krb5<br />
** Status is resolved<br />
** Version_Fixed is (no value)<br />
** Tags is not unsupported<br />
** Tags is not noresource<br />
** Tags is not nochange<br />
* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.<br />
* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y" and push to the authoritative repository.<br />
* Create the new branch and push it to the authoritative repository.<br />
* On the new branch, update README for the new release:<br />
** Make sure that all x.y references are for the new version (they should be already).<br />
** Include the list of major changes for the new release.<br />
** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).<br />
** Copy the list of contributors from the previous release branch.<br />
** Add contributors from the RT tickets for the new release branch.<br />
** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.<br />
* On the master branch, update README for the next prerelease:<br />
** In README, update x.y references to x.(y+1).<br />
** In README, copy the list of contributors from the x.y branch.<br />
** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.<br />
** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.<br />
* Update web pages<br />
** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory<br />
** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS<br />
<br />
==Preparing releases==<br />
<br />
===Pre-mkrel===<br />
<br />
* check copyright years in project-wide stuff<br />
* update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code> (only for minor releases, not patch releases)<br />
* make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code><br />
* <code>make depend</code> and commit if changed, with the commit message "make depend"<br />
* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"<br />
* regenerate localization template <code>(cd po && make update-po)</code> and commit if changed, with the commit message "make update-po"<br />
* manually edit patchlevel.h to reflect the new release<br />
** for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"<br />
** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.<br />
* manually update README<br />
** release dates (in major changes heading, ISO 8601 date format with hyphens)<br />
*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release<br />
** changes<br />
*** note whether bugfix release, maintenance vs current release<br />
*** bullet list of major changes<br />
*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)<br />
** contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)<br />
** double-check dates and release numbers in new section headings<br />
* re-run <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h<br />
** If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run <code>(cd po && make update-po)</code> again. (This should no longer be necessary after {{bug|8560}}.)<br />
* commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"<br />
* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)<br />
<br />
===Running mkrel===<br />
<br />
* <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code><br />
** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar<br />
* manually inspect output for versioning and correctness<br />
** HTML docs<br />
** PDF docs<br />
** patchlevel.h as modified by mkrel<br />
* push release branch commits and release tags to authoritative repository<br />
** you will need to be in hooks.branchers in the authoritative repository to push the tags<br />
<br />
===Post-mkrel===<br />
<br />
* PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)<br />
* copy tar file and signature into /mit/kerberos/dist/krb5/x.y<br />
* for alpha and beta releases:<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release<br />
** symlink index.html to krb5-x.y.html in that directory<br />
** place an entry in /mit/kerberos/dist/testing.html<br />
** send an announcement to krbdev@mit.edu<br />
** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.<br />
** skip all remaining steps<br />
* create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc<br />
* copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig<br />
* copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt<br />
* generate branded HTML docs<br />
** <code>HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html</code><br />
** we don't ship the branded (with logo) docs because the logo is an MIT trademark<br />
** copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html<br />
** repeat for <code>HTML_LOGO=... make pdf</code> and .../doc/pdf<br />
* update RT configuration<br />
** check that https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work<br />
** in the web interface, to go Configuration -> Custom Fields -> Version_Fixed and add a new one for the next patch release<br />
* edit web pages<br />
** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html as an example)<br />
** update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and old news items to oldnews.html<br />
** update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html<br />
** review edited web pages in a web browser and double check that release numbers and release dates have been updated<br />
** update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks<br />
** update /mit/kerberos/krb5-latest symlink if this is a major or minor release<br />
** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html<br />
* send announcement to kerberos-announce<br />
* make followup versioning commit to release branch<br />
** edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"<br />
** use the commit message "Update for krb5-x.y.z-postrelease"<br />
** push this commit to the authoritative repository</div>Ghudson