/usr/share/doc/dacs-examples/man/dacs.conf.5.html is in dacs-examples 1.4.38a-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 | <!-- Copyright (c) 2003-2013 -->
<!-- Distributed Systems Software. All rights reserved. -->
<!-- See the file LICENSE for redistribution information. -->
<!-- $Id: copyright-html 2625 2013-01-22 18:15:12Z brachman $ -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>dacs.conf</title><link rel="stylesheet" type="text/css" href="css/dacsdocs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div id="refentry" class="para16">
<script language="javascript" type="text/javascript" src="css/js/fontselector.js"></script>
<table width="100%"><tr>
<td align="left">
<b>DACS.CONF(5)</b></td>
<td align="center">
<b>DACS Formats and Conventions</b></td>
<td align="right">
<b>DACS.CONF(5)</b></td>
</tr></table>
<div class="refnamediv"><h2>NAME</h2><p>dacs.conf — <span class="command"><strong>DACS</strong></span> configuration files and directives</p></div><div class="refsect1"><a name="idm11"></a><h2>DESCRIPTION</h2><p>These files are part of the <span class="command"><strong>DACS</strong></span> suite.</p><p>Nearly all <span class="command"><strong>DACS</strong></span> services and utilities
consult a configuration file when they start up.
Such things as the per-jurisdiction
locations of access control files and log files,
authentication processing, error handling, and run-time
limits are specified in the configuration file.
The recommended name for this file is <code class="filename">dacs.conf</code>
and the <span class="command"><strong>DACS</strong></span> documentation will generally refer to it
by that name.
Site-wide configuration, which is optional, is typically put
in a file named <code class="filename">site.conf</code>.
Both files are XML documents,
and consist of various <em class="firstterm">sections</em>,
<em class="firstterm">clauses</em>, and <em class="firstterm">directives</em>,
not unlike the <code class="filename">httpd.conf</code> configuration file used by
<span class="command"><strong>Apache</strong></span>.
Different federations and jurisdictions running on the same host may
share these files or each might have its own separate configuration file;
the former is more common since it reduces duplication
and helps to prevent inconsistencies.
</p><p>Federations, jurisdictions, and other important concepts
are discussed in <a class="ulink" href="dacs.1.html#key_concepts" target="_top">dacs(1)</a>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note1"></a>Note</h3><p>Unlike the
"passive" configuration files found in most systems,
the <span class="command"><strong>DACS</strong></span> configuration files are "active"; that is,
configuration directives are evaluated as expressions within a run-time
context that includes information related to the current request, web server,
operating system, and <span class="command"><strong>DACS</strong></span> itself.
By specifying the value of a directive as an expression rather than a
simple string, the configuration under which a request is processed can adapt
to, or depend on, the context in which it is made.
Administrators do not need to use this capability, but it is available
when flexibility is needed.
</p></div><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>Each configuration file is completely read and processed once,
each time a <span class="command"><strong>DACS</strong></span> web service or utility is executed.
Changes to the files take effect the next time the files are read;
no recompilation or special action needs to be taken, and
neither <span class="command"><strong>Apache</strong></span> nor any other server needs to be restarted.
It is usually safe to make minor updates to the configuration files while
<span class="command"><strong>DACS</strong></span> is operational, but it is better to temporarily
deny all access if the web server is busy and more complicated changes
are being made.
Because <span class="command"><strong>DACS</strong></span> components abort if they encounter a
configuration error
(e.g., leading to all access to be denied, all authentication to fail,
or a utility to become non-operational),
temporarily introducing a configuration error will not usually cause any
serious problems.
Under heavy load or if complex authentication methods have been configured,
however, it is prudent to stop the web server briefly while the old
configuration files are replaced with the new ones.
</p></div><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>While it may at first seem that <span class="command"><strong>DACS</strong></span> is difficult
to configure, in practice the default configuration that comes with the
<span class="command"><strong>DACS</strong></span> distribution is sufficient in many cases,
and leaves only a few straightforward, site-dependent directives
to be specified.
Many administrators will never need to use the more advanced configuration
features.
</p></div><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The <span class="command"><strong>DACS</strong></span> distribution includes a
prototype version of <code class="filename">site.conf</code>, found in
<code class="filename">conf/site.conf-std</code>, which establishes reasonable
defaults based on <span class="command"><strong>DACS</strong></span> build-time arguments.
It may need some customization for the local environment.
By default, <span class="command"><strong>DACS</strong></span> looks for the site configuration
file in <code class="filename">federations/site.conf</code>, relative to the
<span class="command"><strong>DACS</strong></span> installation directory;
<code class="filename">conf/site.conf-std</code> can be copied there and any
necessary customizations made.
</p></li><li class="listitem"><p>A command to validate and display configuration,
<a class="ulink" href="dacsconf.1.html" target="_top">dacsconf(1)</a> is available,
as is a simple web service, <a class="ulink" href="dacs_conf.8.html" target="_top">dacs_conf(8)</a>.
Until you become comfortable with configuration files,
consider running one of them after making changes.
A fatal configuration error will prevent <span class="command"><strong>DACS</strong></span> from
running and access to all <span class="command"><strong>DACS</strong></span>-wrapped resources will
be denied.
</p></li></ul></div></div><div class="refsect2"><a name="locating_dacs.conf"></a><h3>Locating dacs.conf and site.conf</h3><p>The locations of <code class="filename">dacs.conf</code> and
<code class="filename">site.conf</code>
may be specified with the web server configuration, in an environment
variable, through a command line flag, or at compile time.
A single configuration file can provide directives for
multiple <span class="command"><strong>DACS</strong></span> jurisdictions.
For example, if a machine is hosting more than one
<span class="command"><strong>DACS</strong></span> jurisdiction, they can each use the same
<span class="command"><strong>DACS</strong></span> binaries.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note33"></a>Note</h3><p>Most
<span class="command"><strong>DACS</strong></span> commands and web services require the
<code class="filename">dacs.conf</code> file to exist;
the exceptions are a few "standalone" programs,
such as <a class="ulink" href="dacshttp.1.html" target="_top">dacshttp(1)</a>.
The <code class="filename">site.conf</code> file is not required;
if a location has been configured and the file exists, however,
it must be readable and by convention should contain default
values appropriate for the installed release.
</p></div><p>Command line flags common to many <span class="command"><strong>DACS</strong></span> programs
are described in <a class="ulink" href="dacs.1.html#dacsoptions" target="_top">dacs(1)</a>.
</p><p>So that <a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a> (which
is invoked by the
<a class="ulink" href="mod_auth_dacs.html" target="_top">mod_auth_dacs</a> module) can find its
configuration,
the location of <code class="filename">dacs.conf</code> can be specified
in <span class="command"><strong>Apache's</strong></span>
<code class="filename">httpd.conf</code> file using the
<span class="property">SetDACSAuthConf</span> directive.
It may instead, however, be specified through the <code class="envar">DACS_CONF</code>
environment variable, on the command line, or using a build-time default.
Similarly, the location of <code class="filename">site.conf</code> can be specified
in <span class="command"><strong>Apache's</strong></span>
<code class="filename">httpd.conf</code> file using the
<span class="property">SetDACSAuthSiteConf</span> directive,
through the <code class="envar">DACS_SITE_CONF</code>
environment variable, on the command line, or using a build-time default.
</p><p>If the location of <code class="filename">dacs.conf</code>
(<code class="filename">site.conf</code>) is not given
at run-time, a compile-time value of the symbol <span class="symbol">DACS_CONF</span>
(<span class="symbol">DACS_SITE_CONF</span>) will be used if possible.
This is the usual case for programs other than <span class="command"><strong>dacs_acs</strong></span>.
It is a fatal error if a <span class="command"><strong>DACS</strong></span> service can't locate
<code class="filename">dacs.conf</code>.
</p><p>Regardless of how the location of <code class="filename">dacs.conf</code>
is specified,
<span class="command"><strong>DACS</strong></span> performs string interpolation on the pathname.
If interpolation fails, <span class="command"><strong>DACS</strong></span> will encounter a fatal error
because it will not be able to locate its configuration file.
</p><div class="refsect3"><a name="interpolation"></a><h4>Path Interpolation</h4><p>Path interpolation is available using a syntax and method
similar to <span class="command"><strong>Apache's</strong></span>
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mod_vhost_alias.html" target="_top"><code class="function">mod_vhost_alias</code></a>
module.
Interpolation is always performed to determine the locations
of several resources used by <span class="command"><strong>DACS</strong></span>,
such as <code class="filename">dacs.conf</code> and <code class="filename">site.conf</code>,
and with <span class="command"><strong>DACS's</strong></span>
<a class="ulink" href="#LOG_FILE" target="_top">LOG_FILE</a> directive,
regardless of the manner in which the location is provided to
<span class="command"><strong>DACS</strong></span>.
It is applied whether the location of <code class="filename">dacs.conf</code>
is specified using the <code class="option">-u</code> command line flag or
the <span class="command"><strong>Apache</strong></span> (<code class="function">mod_auth_dacs</code>)
<span class="property">SetDACSAuthConf</span> directive, for instance.
</p><p>The functionality can also be accessed using the
<a class="ulink" href="dacs.exprs.5.html#pathname" target="_top">pathname()</a> function.
</p><p>The strings that may be interpolated into the pathname are obtained from
the execution environment, in particular the URI authority information
(based on <span class="command"><strong>Apache</strong></span>'s <code class="envar">SERVER_NAME</code>
and <code class="envar">SERVER_PORT</code> environment variables),
the URI service path (described below),
build-time configuration,
and the applicable <code class="literal">Jurisdiction</code> section's
distinguishing URI.
</p><p>Interpolation is controlled by <code class="function">printf</code>-like
format specifiers, as follows:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">%%</code></span></dt><dd><p>Insert a literal percent character
</p></dd><dt><span class="term"><code class="literal">%a</code></span></dt><dd><p>Insert the application name, which is obtained from
the filename component of the program's
<code class="varname"><a name="var_argv0"></a>argv[0]</code> argument
</p></dd><dt><span class="term"><code class="literal">%bA</code></span></dt><dd><p>Insert the absolute pathname of the root of the Apache
installation directory, specified at build-time
(<code class="varname">APACHE_HOME</code>)
</p></dd><dt><span class="term"><code class="literal">%bD</code></span></dt><dd><p>Insert the absolute pathname of the root of the
<span class="command"><strong>DACS</strong></span> installation directory, specified at build-time
(<code class="varname">DACS_HOME</code>)
</p></dd><dt><span class="term"><code class="literal">%p</code></span></dt><dd><p>Insert the port number of the virtual host
(<code class="envar">SERVER_PORT</code>)
</p></dd><dt><span class="term"><code class="literal">%<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>M</code></em></code></span></dt><dd><p>Insert one or more components of the name,
or a substring of those subcomponents.
<em class="replaceable"><code>N</code></em> and <em class="replaceable"><code>M</code></em>
are numbers used to select part of the <code class="envar">SERVER_NAME</code> string
(a domain name or IP address).
<em class="replaceable"><code>N</code></em> selects from the dot-separated components of
<code class="envar">SERVER_NAME</code>, while
<em class="replaceable"><code>M</code></em> selects characters within whatever
<em class="replaceable"><code>N</code></em> has selected.
<em class="replaceable"><code>M</code></em> is optional and defaults to zero if it
isn't present.
The dot must be present if and only if <em class="replaceable"><code>M</code></em>
is also present.
If <em class="replaceable"><code>N</code></em> or <em class="replaceable"><code>M</code></em> are greater
than the number of parts available, a single underscore is interpolated.
The numbers are interpreted as follows:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">0</code> or <code class="literal">1+</code> or
<code class="literal">-1+</code></span></dt><dd><p>the whole name</p></dd><dt><span class="term"><code class="literal">1</code></span></dt><dd><p>the first part</p></dd><dt><span class="term"><code class="literal">2</code></span></dt><dd><p>the second name</p></dd><dt><span class="term"><code class="literal">-1</code></span></dt><dd><p>the last part</p></dd><dt><span class="term"><code class="literal">-2</code></span></dt><dd><p>the next-to-last part</p></dd><dt><span class="term"><code class="literal">2+</code></span></dt><dd><p>the second and all following parts</p></dd><dt><span class="term"><code class="literal">-2+</code></span></dt><dd><p>the next-to-last and all preceding parts</p></dd></dl></div><p>
</p></dd><dt><span class="term"><code class="literal">%s[<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>M</code></em>]</code></span></dt><dd><p>This is a synonym for
<code class="literal">%<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>M</code></em></code>,
with <code class="literal">%s</code> being equivalent to
<code class="literal">%0</code>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note2"></a>Note</h3><p>In cases where the character following
<code class="literal">%s</code> should not be interpreted as part of the format, it
must be escaped (e.g., <code class="literal">%s%2</code>).
</p></div><p>
</p></dd><dt><span class="term"><code class="literal">%u[<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>M</code></em>]</code></span></dt><dd><p>This functions like the <code class="literal">%s</code> specifier
except that it is applied to the
URI service path (described below) for the current request,
which has slash-separated components.
<code class="literal">%u</code> is equivalent to <code class="literal">%u0</code>.
For example, if the URI service path is
"<span class="path">example.com/metalogic</span>",
<code class="literal">%u1</code> would be "<code class="literal">example.com</code>",
<code class="literal">%u2</code> would be "<code class="literal">metalogic</code>",
and <code class="literal">%u0</code>
(and <code class="literal">%u</code> and <code class="literal">%u1+</code>) would be
"<span class="path">example.com/metalogic</span>".
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note3"></a>Note</h3><p>In cases where the character following
<code class="literal">%u</code> should be interpolated verbatim and not interpreted as
part of the specifier, it must be escaped (e.g., <code class="literal">%u%2</code>).
</p></div><p>
</p></dd><dt><span class="term"><code class="literal">%U[<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>M</code></em>]</code></span></dt><dd><p>This functions like the <code class="literal">%u</code> specifier
except that it is applied to the applicable
<a class="ulink" href="#jurisdiction_section" target="_top">Jurisdiction section's</a>
distinguishing URI (described below).
<code class="literal">%U</code> is equivalent to <code class="literal">%U0</code>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note4"></a>Note</h3><p>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Because the applicable <code class="literal">Jurisdiction</code>
section is not known until after configuration processing has started,
this specifier cannot be used to describe the location of configuration files.
</p></li><li class="listitem"><p>In cases where the character following
<code class="literal">%U</code> should be interpolated verbatim and not interpreted as
part of the specifier, it must be escaped (e.g., <code class="literal">%U%2</code>).
</p></li></ul></div><p>
</p></div><p>
</p></dd><dt><span class="term">Other format specifiers</span></dt><dd><p>If a <code class="literal">%</code> is followed by an unrecognized
specifier, that character is inserted verbatim.</p></dd><dt><span class="term">Other characters</span></dt><dd><p>All other characters are inserted verbatim</p></dd></dl></div><p>For example, if <code class="envar">SERVER_NAME</code> is
<span class="domainname">dss.example.com</span>
and <code class="envar">SERVER_PORT</code> is <code class="literal">8080</code>,
then the <span class="command"><strong>Apache</strong></span> directive:
</p><pre class="screen">
SetDACSAuthConf dacs-acs "/usr/local/apache2/conf/dacs/%2+/dacs.conf"
</pre><p>
will expand the path to
<code class="filename">/usr/local/apache2/conf/dacs/example.com/dacs.conf</code>.
The command line flag:
</p><pre class="screen">
-c /usr/local/dacs/%1%.%p/dacs.conf
</pre><p>
specifies the location of the configuration file to be
<code class="filename">/usr/local/dacs/dss.8080/dacs.conf</code>.
</p><p>The <code class="literal">%u</code> specifier interpolates the
URI service path, or portions thereof, which is the string
<code class="envar">HTTP_HOST</code><code class="literal">/</code><code class="envar">REQUEST_URI</code>
(without a query component).
When a <span class="command"><strong>DACS</strong></span> service is invoked as a CGI, this will
be the usual case; the URI service path is undefined if either of those
environment variables is unavailable, however.
</p></div></div><div class="refsect2"><a name="file_format"></a><h3>File Format</h3><p><code class="filename">dacs.conf</code>
is an XML document that conforms to
<a class="ulink" href="../dtd-xsd/Configuration.dtd" target="_top">Configuration.dtd</a>.
</p><p>A <code class="filename">dacs.conf</code> file consists of
an optional <code class="literal">Default</code> section followed by zero or more
<code class="literal">Jurisdiction</code> sections.
Either type of section consists of
<span class="command"><strong>DACS</strong></span> directives or XML elements, called
<em class="firstterm">clauses</em>, that contain
<span class="command"><strong>DACS</strong></span> directives.
There are three kinds of clauses: <code class="literal">Auth</code> clauses,
<code class="literal">Roles</code> clauses, and <code class="literal">Transfer</code> clauses.
</p><p>Just to give its flavour, here's an
incomplete <code class="filename">dacs.conf</code> file:</p><a name="example_dacs.conf"></a><pre class="programlisting">
<Configuration>
<Default>
LOG_FILE "${Conf::DACS_HOME}/logs/logfile"
FEDERATION_DOMAIN "example.com"
FEDERATION_NAME "ROOT"
LOG_LEVEL "notice"
SSL_PROG "/usr/local/dacs/bin/sslclient"
</Default>
<!-- Configuration of first jurisdiction -->
<Jurisdiction uri="dss.example.com">
JURISDICTION_NAME "DSS"
<Auth id="auth_name">
URL "https://dss.example.com/cgi-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
</Auth>
</Jurisdiction>
<!-- Configuration of second jurisdiction -->
<Jurisdiction uri="dss.example.com/foo">
JURISDICTION_NAME "FOO"
</Jurisdiction>
<!-- Configuration of third jurisdiction -->
<Jurisdiction uri="metalogic.example.com">
JURISDICTION_NAME "METALOGIC"
</Jurisdiction>
</Configuration>
</pre><p>The structure of
<code class="filename">site.conf</code> is only slightly different.
The <code class="literal">Default</code> section is mandatory in
<code class="filename">site.conf</code>
and no <code class="literal">Jurisdiction</code> sections are allowed.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note5"></a>Note</h3><p>Because the configuration files are XML documents,
characters special to XML must be properly escaped.
In particular, an ampersand character must always be written as
<code class="literal">&amp;</code>
and a <code class="literal"><</code> character must be written as
<code class="literal">&lt;</code>.
</p></div><p>Although the XML format of the
<span class="command"><strong>DACS</strong></span> configuration files is easily understood
and fairly readable, and they can be modified using any text editor,
there is nothing to prevent a special-purpose tool from being used.
</p></div><div class="refsect2"><a name="idm329"></a><h3>The <code class="literal">Default</code> Section</h3><p>The purpose of the <code class="literal">Default</code> section in
<code class="filename">dacs.conf</code> is to establish default values for
directives that tend to be shared amongst all of the
<code class="literal">Jurisdiction</code> sections that appear in
<code class="filename">dacs.conf</code>.
The <code class="literal">Default</code> section is optional;
if present, it must appear before any <code class="literal">Jurisdiction</code>
section in <code class="filename">dacs.conf</code>.
</p><p>The <code class="filename">site.conf</code> file, if it exists, consists of
only a <code class="literal">Default</code> section.
Directives that are common to all of a site's
<code class="filename">dacs.conf</code> files might be put in
<code class="filename">site.conf</code>.
</p><p>Any configuration directive or clause may appear in the
<code class="literal">Default</code> section.
</p></div><div class="refsect2"><a name="jurisdiction_section"></a><h3>The
<code class="literal">Jurisdiction</code> Section</h3><p>Each <code class="literal">Jurisdiction</code> section contains
configuration directives that are associated with a particular jurisdiction.
These directives override those found anywhere else, as described below.
</p></div><div class="refsect2"><a name="merging"></a><h3>Section Merging and Directive Evaluation</h3><p>The three types of configuration sections are merged as follows.
First, directives and clauses that appear in the <code class="filename">site.conf</code>
<code class="literal">Default</code> section are overridden by those that appear
in the <code class="filename">dacs.conf</code> <code class="literal">Default</code> section.
The resulting directives and clauses are in turn overridden by those that
appear in the selected <code class="literal">Jurisdiction</code> section.
Usually, <code class="filename">site.conf</code> will contain the standard default
directives that come with the installed release of <span class="command"><strong>DACS</strong></span>,
the <code class="filename">dacs.conf</code> <code class="literal">Default</code> section
will contain directives common to all of the jurisdictions defined on the
host that are in the same federation,
and each <code class="literal">Jurisdiction</code> section will contain
directives specific to that jurisdiction.
</p><p>The exception to this merging procedure is directives in the
<a class="ulink" href="#directive_categories" target="_top"><code class="literal">Stack</code>
category</a>.
Instead of overriding, these directives accumulate.
</p><p>The order in which directives (but not clauses) appear within
a section is not significant, even with respect to references
to variables in the <code class="varname">Conf</code>
<a class="ulink" href="dacs.exprs.5.html#variables" target="_top">namespace</a>,
with the exception of the
<a class="ulink" href="#EVAL" target="_top"><span class="property">EVAL</span> directive</a>.
</p><p>Only after directives in the three sections are merged are
their right-hand sides evaluated
(again, with the exception of
<a class="ulink" href="#EVAL" target="_top"><span class="property">EVAL</span></a>)
to determine the value of each directive.
Therefore, if a directive appears in both the
<code class="literal">Default</code> section and the <code class="literal">Jurisdiction</code>
section, the instances in the <code class="literal">Default</code> section will not
have their directive values evaluated; they will simply be discarded
(with the exception of the <code class="literal">Stack</code> directive category).
</p><div class="refsect3"><a name="undef"></a><h4>The undef() directive</h4><p>As a special case,
if a directive is given the special value returned by
<a class="ulink" href="dacs.exprs.5.html#undef" target="_top">undef()</a>,
the instance of the directive is deleted.
This provides a way to conditionally include or exclude a directive
depending on the execution environment.
For example, this directive increases the debugging level for
<span class="command"><strong>DACS</strong></span> web services but not for commands:
</p><pre class="programlisting">
LOG_LEVEL ${Env::REMOTE_ADDR:e} ? "TRACE" : undef()
</pre><p>
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note6"></a>Note</h3><p>Because
of the way configuration files are currently processed,
the check for directive category satisfaction happens
<span class="emphasis"><em>before</em></span> right-hand side evaluation.
This means that in any particular section only one instance of a
given directive in the <code class="literal">Required1</code> category may appear
(see <a class="ulink" href="#directive_categories" target="_top">Directive Categories</a>),
even if just one would be included after the evaluation step.
</p></div><p>
</p></div><div class="refsect3"><a name="idm391"></a><h4>Fatal errors</h4><p>It is a fatal error to reference an undefined variable unless
the <code class="literal">e</code> or <code class="literal">?</code>
<a class="ulink" href="dacs.exprs.5.html#variable_modifiers" target="_top">modifier flag</a>
is used in the variable reference.
Recursive variable references are detected and result in a fatal error.
If a directive ends up not being evaluated, it does not matter whether
its right-hand side is invalid (or would be if evaluated).
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note7"></a>Note</h3><p>When a fatal error occurs during configuration processing,
a <span class="command"><strong>DACS</strong></span> web service tries to terminate gracefully.
But because directives (including error handling directives) may not have
been processed correctly, or even at all, there is no
guarantee that an error handler
(such as one defined by the
<a class="ulink" href="#ACS_ERROR_HANDLER" target="_top">ACS_ERROR_HANDLER</a> directive)
will be invoked or a requested output format will be honoured during
abnormal termination.
A non-zero exit process status is always returned.
</p></div></div><div class="refsect3"><a name="idm401"></a><h4>An example</h4><p>Consider the following configuration excerpts:
</p><pre class="programlisting">
# In site.conf:
LOG_LEVEL "debug"
# In the dacs.conf Default section:
LOG_LEVEL "notice"
# In the dacs.conf Jurisdiction section:
LOG_LEVEL "trace"
</pre><p>
After configuration processing, the directive <span class="property">LOG_LEVEL</span>
will be set to "<code class="literal">trace</code>",
and the variable
<code class="varname"><a name="var_conf_log_level"></a>${Conf::LOG_LEVEL}</code> will have that
value during configuration processing.
</p><p>Here are some excerpts from a <code class="filename">dacs.conf</code> file:
</p><pre class="programlisting">
# In the Default section:
FEDERATION_DOMAIN "example.com"
FEDERATION_NAME "EXAMPLE"
# In the Jurisdiction section:
JURISDICTION_NAME "DEMO"
VFS "[abc]dacs-fs:${Conf::FEDERATIONS_ROOT}/${Conf::FEDERATION_DOMAIN}\
/${Conf::JURISDICTION_NAME}/abc"
</pre><p>
When computing the <span class="property">VFS</span> directive's value in the
example above,
the values of the <code class="varname">FEDERATIONS_ROOT</code> variable
(determined at build-time) and the
<span class="property">FEDERATION_DOMAIN</span> and
<span class="property">JURISDICTION_NAME</span> configuration directives are
interpolated.
Directives in <code class="filename">site.conf</code> may reference configuration
variables that are defined in <code class="filename">dacs.conf</code>.
</p><p>Given the configuration:
</p><pre class="programlisting">
# In site.conf:
VFS "[dtds]dacs-fs:/usr/local/dacs/www/dtd-xsd"
# In the dacs.conf Default section:
VFS "[dtds]dacs-fs:/usr/local/dacs/dtd-xsd"
# In the dacs.conf Jurisdiction section:
VFS "[dtds]dacs-fs:/export/dacs/dtd-xsd"
VFS "[xxx]dacs-fs:/export/dacs/xxx"
</pre><p>
All four <span class="property">VFS</span> directives will be in effect, but
they will be ordered such that the first one in the
<code class="literal">Jurisdiction</code> section is at the top of the stack,
the second one in that section is next on the stack,
the directive in the <code class="filename">dacs.conf</code>
<code class="literal">Default</code> section follows,
and the one from <code class="filename">site.conf</code> is last.
</p></div></div><div class="refsect2"><a name="jurisdiction_section_overview"></a><h3>Jurisdiction
Section Selection</h3><p><span class="command"><strong>DACS</strong></span> web services and commands do not have any
federation or jurisdiction information compiled into them, so that
a single set of <span class="command"><strong>DACS</strong></span> binaries can be shared by many
jurisdictions
(e.g., by multiple real or virtual web servers on the same host, or using NFS
or some other file sharing mechanism).
But it means that (most) web services and commands need a run-time mechanism to
determine "who they are" - which federation and jurisdiction are they
acting on behalf of?
For web services, this usually depends on the server name, hostname, port,
scheme, URI path, some other context associated with the request,
or a combination of these things.
But it is sometimes most convenient to specify a jurisdiction name
and have <span class="command"><strong>DACS</strong></span> work out what the request URIs to that
jurisdiction look like, if it needs to.
</p><p>Most <span class="command"><strong>DACS</strong></span> web services and commands need to
obtain run-time configuration information for the jurisdiction they represent.
Because <code class="filename">dacs.conf</code> may specify the configuration of
more than one jurisdiction, how do they know which
<code class="literal">Jurisdiction</code> section they should use?
In cases where <span class="command"><strong>DACS</strong></span> does not know the jurisdiction name,
it searches for the correct <code class="literal">Jurisdiction</code> section and then
determines the name of the jurisdiction; in cases where it is given the
jurisdiction name, it searches <code class="literal">Jurisdiction</code> sections to
find one with a directive that identifies the jurisdiction that it was given.
</p><p>The applicable <code class="literal">Jurisdiction</code> section to use for a
particular web service request or command can be determined in a variety of
ways, using:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>the <code class="option">-u</code> command line flag to specify
a <em class="replaceable"><code>config-uri</code></em> that is matched against
<a class="ulink" href="#jurisdiction_section_uri" target="_top">effective jurisdictional URIs</a>;
</p></li><li class="listitem"><p>the <code class="option">-uj</code> command line flag to specify
a <em class="replaceable"><code>jurisdiction-name</code></em> that is matched against
<code class="literal">Jurisdiction</code> sections'
<span class="property">JURISDICTION_NAME</span> directive;
</p></li><li class="listitem"><p>the <code class="option">-us</code> command line flag to indicate
that there is only a single <code class="literal">Jurisdiction</code> section,
so that section should be selected; or
</p></li><li class="listitem"><p>by matching a request URI against
<a class="ulink" href="#jurisdiction_section_uri" target="_top">effective jurisdictional URIs</a>.
</p></li></ul></div><p>
</p><p>Command line flags are described in
<a class="ulink" href="dacs.1.html#dacsoptions" target="_top">dacs(1)</a>,
as is the <code class="envar">DEFAULT_JURISDICTION</code> environment variable.
</p><p>These methods will be described individually shortly.
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>Because selection of the applicable <code class="literal">Jurisdiction</code>
section is quite flexible, it may seem complicated.
In practice, however, it is often rather simple, and particularly so if only
one jurisdiction is being configured.
It may be sufficient to read this section and skip the detail presented
in the remainder of the discussion on how the <code class="literal">Jurisdiction</code>
section is selected.
</p></div><p>If there is only one jurisdiction, its <code class="literal">uri</code>
attribute value can simply be the domain name associated with the jurisdiction.
Any of the command line flags could then be used (or none).
If the jurisdiction's domain name is
<span class="domainname">foo.example.com</span>, for instance,
the <code class="literal">Jurisdiction</code> section in
<code class="filename">dacs.conf</code> might look like:
</p><pre class="programlisting">
<Configuration>
<Jurisdiction uri="foo.example.com">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
</pre><p>
</p><p>In the <span class="command"><strong>Apache</strong></span> configuration file
(<code class="filename">httpd.conf</code>), one might specify:
</p><pre class="screen">
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-u foo.example.com"
</pre><p>
(which tells <span class="command"><strong>DACS</strong></span> that all web service requests from the
web server or virtual host to which this directive applies should be associated
with the domain <span class="domainname">foo.example.com</span> for
configuration purposes),
or
</p><pre class="screen">
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-us"
</pre><p>
(telling <span class="command"><strong>DACS</strong></span> that all web service requests from the
web server or virtual host to which this directive applies should be
associated with the only jurisdiction described in the configuration file,
whatever that jurisdiction may be),
or
</p><pre class="screen">
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-uj FOO"
</pre><p>
(telling <span class="command"><strong>DACS</strong></span> that all web service requests from the
web server or virtual host to which this directive applies should be
associated with jurisdiction <code class="literal">FOO</code>),
or simply
</p><pre class="screen">
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs
</pre><p>
In the last case, <span class="command"><strong>DACS</strong></span> will match the request URI
(which presumably looks like
<span class="uri">https://foo.example.com/...</span>)
against <span class="domainname">foo.example.com</span>.
</p><p>Multiple jurisdictions that are identified by distinct
domain names are also easily configured once a <span class="command"><strong>DACS</strong></span>
administrator decides how he would like request URIs to identify them.
This is usually done much like this:
</p><pre class="programlisting">
<Configuration>
<Jurisdiction uri="foo.example.com">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="baz.example.com">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
</pre><p>
And so that the domain name in the request URI is matched against the
jurisdiction's effective URI, one would use:
</p><pre class="screen">
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs
</pre><p>
</p><p>Multiple jurisdictions that share a domain name but are
distinguished by a portion of the request URI pathname component,
are often configured something like:
</p><pre class="programlisting">
<Configuration>
<Jurisdiction uri="example.com/foo">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="example.com/baz">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
</pre><p>
And again using:
</p><pre class="screen">
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs
</pre><p>
With this style of configuration, a request for
<span class="url">https://example.com/foo/cgi-bin/dacs/blah</span>
would be directed to the configuration for the <code class="literal">FOO</code>
jurisdiction.
</p><p>Similarly, port numbers can also be used for
<code class="literal">Jurisdiction</code> section selection:
</p><pre class="programlisting">
<Configuration>
<Jurisdiction uri="example.com:443">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="example.com:8443">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
</pre><p>
</p><p>Lastly, a hostname wildcard syntax can be useful:
</p><pre class="programlisting">
<Configuration>
<Jurisdiction uri="*.foo.example.com">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="*.baz.example.com">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
</pre><p>
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="important1"></a>Important</h3><p>No
check is made to ensure that the jurisdiction sections are unique.
This is sometimes a useful feature but can also cause unexpected behaviour.
It is probably best for all but the most advanced administrators to
make sure that the same <span class="property">JURISDICTION_NAME</span> directive
doesn't appear in multiple <code class="literal">Jurisdiction</code> sections
and that each section has a different effective jurisdictional URI.
</p></div><p>If your particular requirement has been covered,
it is probably safe to skip the detail that follows.
</p><div class="refsect3"><a name="jurisdiction_section_uri"></a><h4>The Effective Jurisdictional
URI</h4><p>A <code class="literal">Jurisdiction</code> element must have either a
<code class="literal">uri</code> attribute or a
<code class="literal">uri_expr</code> attribute, but not both.
If the latter is given, it specifies an
<a class="ulink" href="dacs.exprs.5.html" target="_top">expression</a> that
is evaluated at configuration processing time.
The <em class="firstterm">effective jurisdictional URI</em>
(or the jurisdiction's <em class="firstterm">effective URI</em>)
is either the value of the <code class="literal">uri</code> attribute
or the value obtained by evaluating the <code class="literal">uri_expr</code> attribute.
The effective jurisdictional URI can be matched against
a request's URI or the <code class="option">-u</code> flag's
<em class="replaceable"><code>config-uri</code></em> to
find the applicable <code class="literal">Jurisdiction</code> section.
</p><p>The standard set of
<a class="ulink" href="#config-vars" target="_top">configuration variables</a>
in the <code class="varname">Conf</code> and <code class="varname">Env</code>
<a class="ulink" href="dacs.exprs.5.html#variables" target="_top">namespace</a>
(<span class="emphasis"><em>but no others</em></span>)
are accessible during evaluation of <code class="literal">uri_expr</code>.
Consider this partial configuration:
</p><pre class="screen">
<Jurisdiction uri_expr="${Env::SERVER_NAME}">
</pre><p>
Here, the effective jurisdictional URI is
the value of the <code class="envar">SERVER_NAME</code> environment variable.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note8"></a>Note</h3><p>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The environment established for a
<span class="command"><strong>DACS</strong></span> web service and
the environment of a <span class="command"><strong>DACS</strong></span> command are typically different,
so programs run from the command line may fail if
<code class="literal">uri_expr</code> references an undefined variable.
</p></li><li class="listitem"><p>Any error that occurs during evaluation of
<code class="literal">uri_expr</code> is fatal.
</p></li><li class="listitem"><p>One application of the <code class="literal">uri_expr</code> attribute is
constructing a generic or "template" <code class="literal">Jurisdiction</code> section.
For example, if multiple domain names need to map to the same jurisdiction,
a <code class="literal">uri_expr</code> like the following can be used:
</p><pre class="screen">
<Jurisdiction uri_expr="regmatch(${Env::SERVER_NAME}, '(foo.example.com)|(baz.example.com)')">
</pre><p>
</p></li></ul></div><p>
</p></div><p>
</p><p>The effective jurisdictional URI has the following syntax:
</p><pre class="programlisting">
uri -> [scheme-spec] [domain-spec] [":" port-spec] [path-spec]
scheme-spec -> "http://" | "https://"
domain-spec -> domain-name | "*." domain-name | IP-address
port-spec -> positive-integer | positive-integer "," port-spec
path-spec -> "/" path-segment | "/" path-segment path-spec
</pre><p>
</p></div><div class="refsect3"><a name="selection_by_uri"></a><h4>Jurisdiction Selection by URI</h4><p>Whether the <code class="literal">Jurisdiction</code> section is selected based
on the <code class="option">-u</code> flag's explicit
<em class="replaceable"><code>config-uri</code></em> or
the request URI provided to <span class="command"><strong>DACS</strong></span> through environment
variables,
the effective jurisdictional URIs are matched against the provided URI.
</p><p>An effective jurisdictional URI has the following semantics
for matching against the provided URI:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If <code class="literal">uri</code> specifies the
<code class="literal">http</code> scheme, the provided UR must not have used SSL/TLS;
if <code class="literal">uri</code> specifies the
<code class="literal">https</code> scheme, the provided URI must have used SSL/TLS;
if neither scheme is specified, the scheme is immaterial.
</p></li><li class="listitem"><p>The optional <em class="replaceable"><code>domain-spec</code></em> specifies
a domain name to match (case-insensitively) against the provided URI.
If the initial component of <em class="replaceable"><code>domain-spec</code></em> is
"<code class="literal">*.</code>", then only the components that follow it
in <em class="replaceable"><code>domain-spec</code></em> need to match
the domain name in the provided URI.
For example, <code class="literal">*.example.com</code> matches
<code class="literal">example.com</code> and <code class="literal">foo.baz.example.com</code>.
If the <em class="replaceable"><code>domain-spec</code></em> is omitted, the
domain name in the provided URI is immaterial.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note9"></a>Note</h3><p>The matching algorithm does not consider domain names that
map to the same IP address (i.e., aliases) to be equivalent.
</p></div><p>
</p><p>The <em class="replaceable"><code>domain-spec</code></em> can be an
IP address, but in this case the provided URI must also use an
IP address for the two to match.
That is, no mapping between IP addresses and domain names is performed.
</p></li><li class="listitem"><p>The optional <em class="replaceable"><code>port-spec</code></em> consists of
one or more port numbers, any one of which must match the one specified
<span class="emphasis"><em>explicitly</em></span>
(i.e., not by default) in the provided URI.
If the provided URI does not contain a port, it will not match any
<em class="replaceable"><code>port-spec</code></em>.
Port numbers are separated by a comma (with no embedded whitespace).
If the <em class="replaceable"><code>port-spec</code></em> is omitted, the port number
in the provided URI is immaterial.
</p></li><li class="listitem"><p>The optional <em class="replaceable"><code>path-spec</code></em> must
match the prefix of the provided URI's path component.
Matching is case-sensitive and is performed on corresponding
<em class="replaceable"><code>path-segment</code></em> elements.
</p></li></ul></div><p>
</p><p>The matching algorithm first rejects any <code class="literal">Jurisdiction</code>
section having an effective jurisdictional URI
that does not satisfy the <em class="replaceable"><code>scheme-spec</code></em>
or the <em class="replaceable"><code>domain-spec</code></em>.
It looks for the section that contains a matching
<em class="replaceable"><code>port-spec</code></em> and that has the longest
matching <em class="replaceable"><code>path-spec</code></em>; the first such section
will be selected.
If no such section is found, however, it looks for the section that does not
contain a <em class="replaceable"><code>port-spec</code></em> and that has the longest
matching <em class="replaceable"><code>path-spec</code></em>; the first such section
will be selected.
It is a fatal error if no section can be selected.
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>While configuration of the <code class="literal">uri</code> attribute
may appear to be complex, its value will typically be a simple hostname,
or a simple hostname followed by a jurisdiction-distinguishing initial
path element, as in the example above.
The flexible syntax allows jurisdictions to be associated with requests
based on port numbers, use of SSL/TLS, etc. and lets dissimilar requests
map to the same jurisdiction.
</p></div><p>For example, given the
<a class="ulink" href="#example_dacs.conf" target="_top">example configuration</a> above,
if the request URL is:
</p><pre class="programlisting">
https://dss.example.com/foo/cgi-bin/dacs_authenticate
</pre><p>
then the second <code class="literal">Jurisdiction</code> section will be used.
</p><p>If the request URL is:
</p><pre class="programlisting">
https://dss.example.com/cgi-bin/dacs_authenticate
</pre><p>
then the first <code class="literal">Jurisdiction</code> section will be used.
</p><p>If a <span class="command"><strong>DACS</strong></span> utility is invoked with the command line
flag <code class="option">-u</code> <code class="literal">metalogic.example.com</code>,
the third <code class="literal">Jurisdiction</code> section will be used.
</p></div><div class="refsect3"><a name="idm610"></a><h4>Jurisdiction Selection by Jurisdiction Name</h4><p>The applicable <code class="literal">Jurisdiction</code> section can be
selected by providing the jurisdiction's name.
The <code class="option">-uj</code> flag's <em class="replaceable"><code>jurisdiction-name</code></em>
argument is compared against the <span class="emphasis"><em>unevaluated</em></span>
value of each section's
<span class="property">JURISDICTION_NAME</span> directive until the first exact
string match is found; the section containing the directive will be
selected.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note10"></a>Note</h3><p>Because the
unevaluated value of the directive is used,
if the value of a <span class="property">JURISDICTION_NAME</span>
is not a simple string, this option will not work unless
<em class="replaceable"><code>jurisdiction-name</code></em> is that expression, not its value.
Appropriate quotes are implied around
<em class="replaceable"><code>jurisdiction-name</code></em>, so they should be omitted
on the command line.
</p><p>For example, given the (partial) configuration file entry:
</p><pre class="screen">
<Jurisdiction uri="demo.example.com">
JURISDICTION_NAME "DEMO"
...
</Jurisdiction>
</pre><p>
the command line argument "<code class="option">-uj</code> <code class="literal">DEMO</code>"
would select that jurisdiction section.
If instead <span class="property">JURISDICTION_NAME</span> were an expression
that <span class="emphasis"><em>evaluated</em></span> to the string <code class="literal">DEMO</code>,
the argument would not select that jurisdiction section.
</p></div></div><div class="refsect3"><a name="idm630"></a><h4>Jurisdiction Selection by Default</h4><p>If <code class="filename">dacs.conf</code> contains a single
<code class="literal">Jurisdiction</code> section, the <code class="option">-us</code>
flag can be used to select it without regard to the jurisdiction's name
or effective jurisdictional URI.
This can be particularly useful during testing.
</p><p>Should there be more than one <code class="literal">Jurisdiction</code> section
when this flag is used, a fatal error will occur.
</p></div><div class="refsect3"><a name="idm638"></a><h4>The Distinguishing URI</h4><p>Regardless of how the <code class="literal">Jurisdiction</code> section
is selected, that section's effective jurisdictional URI is matched
against the <code class="option">-u</code> flag's <em class="replaceable"><code>config-uri</code></em>,
if given, or the request URI according to the method described for
<a class="ulink" href="#selection_by_uri" target="_top">Jurisdiction Selection by URI</a>.
The resulting string is called the <em class="firstterm">distinguishing URI</em>.
This string is another way of identifying the selected
<code class="literal">Jurisdiction</code> section and can be used for
<a class="ulink" href="#interpolation" target="_top">string interpolation</a>.
It is also related to the <code class="literal">shared</code> attribute used
in <a class="ulink" href="dacs.acls.5.html" target="_top">access control rules</a>.
</p><p>For example, if the request URI is
<span class="uri">http://foo.example.com/a/b/c</span> and the
matching effective jurisdictional URI is
<span class="uri">*.example.com/a/b</span>,
then the distinguishing URI is
<span class="uri">foo.example.com/a/b</span>.
</p></div></div><div class="refsect2"><a name="idm654"></a><h3>Directives</h3><p>Each directive consists of a directive name,
followed by whitespace (spaces and/or tabs), followed by its value.
Directive names are case-sensitive and comprised of printable characters,
except the space character, and are upper case.
</p><p>A directive value is an expression or sequence of expressions
(<a class="ulink" href="dacs.exprs.5.html" target="_top">dacs.exprs(5)</a>)
that is evaluated at run time during configuration processing.
Here are some directives that are equivalent (on a Saturday):
</p><pre class="screen">
AUTH_FAIL_DELAY_SECS 2
AUTH_FAIL_DELAY_SECS "2"
AUTH_FAIL_DELAY_SECS 1 + 1
AUTH_FAIL_DELAY_SECS strftime("%a") eq:i "Sat" ? 2 : 17
</pre><p>
</p><p>Blank lines, leading white space, and lines whose first non-white space
character is a <code class="literal">#</code> character (i.e., comments) are ignored.
</p><p>Any directive line may be split over physical lines by escaping the
newline character, for example:
</p><pre class="programlisting">
ACS_ERROR_HANDLER "902 'Access denied, \
user not authenticated'"
</pre><p>
</p><p>Processing an unrecognized directive name causes a fatal error,
as does an error encountered during expression evaluation.
</p><div class="refsect3"><a name="evaluated_directives"></a><h4>Evaluated Directives</h4><p>Some directive names end with a <code class="literal">*</code> character.
By convention, this means that the directive's value will be evaluated
a second time,
in the context of a particular module or service request,
but only if the directive value is actually needed.
This allows a configuration directive to reference a variable that
cannot be instantiated until normal configuration file processing has
been performed, for instance.
The values of these directives usually appear within
single quotes so that they initially evaluate to the string between the quotes.
</p><p>Consider this
<a class="ulink" href="dacs_authenticate.8.html#INIT*" target="_top">INIT*</a> directive,
which might appear within an
<a class="ulink" href="dacs_authenticate.8.html#auth_clause" target="_top">Auth clause</a>:
</p><pre class="programlisting">
INIT* '${Auth::CURRENT_USERNAME} = "goa\\" . ${Auth::CURRENT_USERNAME}'
</pre><p>
Because the directive's value appears within single quotes,
the quoted expression is not evaluated during the first scan of the directive
(or more accurately, it evaluates to an unquoted expression);
this is as it should be because the value of the referenced variable
is not known at that time, nor has it been determined whether the
directive will even be needed.
Later,
if the <code class="literal">Auth</code> clause containing this directive is used,
the variable's value is presumably known and
the formerly quoted expression is evaluated,
yielding a final value for the directive.
</p></div><div class="refsect3"><a name="directive_categories"></a><h4>Directive Categories</h4><p>After <a class="ulink" href="#merging" target="_top">section merging</a> is performed,
some directives must be specified while others are optional.
Some may appear at most once and others may be repeated.
The following labels are used to categorize directives:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Required1</code>:</span></dt><dd><p>Directives of this category must be defined and
must appear only once after merging.
</p></dd><dt><span class="term"><code class="literal">Required1-C</code>:</span></dt><dd><p>Under certain conditions, these directives must be
defined and appear only once after merging,
otherwise they need not appear.
For example, some directives are required if and only if the module that
requires them is configured.
</p></dd><dt><span class="term"><code class="literal">Required</code>:</span></dt><dd><p>These directives must always be specified at least once
after merging, and may be repeated.
</p></dd><dt><span class="term"><code class="literal">Optional1</code>:</span></dt><dd><p>These directives may appear at most once after merging.
</p></dd><dt><span class="term"><code class="literal">Optional</code>:</span></dt><dd><p>These directives may appear zero or more times after merging.
</p></dd><dt><span class="term"><code class="literal">Stack</code>:</span></dt><dd><p>This is like the <code class="literal">Optional</code> type,
in that the directive may appear multiple times in any section,
except the usual section merging algorithm is not used.
Instead, all occurrences of the directive in the
<code class="literal">Jurisdiction</code> section,
then in the <code class="literal">Default</code> section of
<code class="filename">dacs.conf</code>,
and then in <code class="filename">site.conf</code> will be
"stacked", in the order in which they appear in each section.
Selection is dependent on the particular directive, which will effectively
search the directives in the <code class="literal">Jurisdiction</code> section first
to find an applicable directive, then search the directives in the
<code class="literal">Default</code> section of <code class="filename">dacs.conf</code>
if necessary, and finally search <code class="filename">site.conf</code> if
necessary.
</p></dd></dl></div><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note11"></a>Note</h3><p>A
directive marked <code class="literal">Deprecated</code> will be
removed in a future version and should not be used.
</p></div><p>Some directives have more complicated constraints on their usage;
they might be allowed only in certain contexts or are required
only in certain situations
(e.g., directives associated with proxied operation are only required if that
mode of operation is being used).
</p><p>Required directives must be present and assigned a valid value, although
the validity of a value is only checked if the directive is actually used.
It is okay to define directives that are not used;
for example, directives related to InfoCards may appear in a configuration
file even if InfoCard support is not enabled at the time
<span class="command"><strong>DACS</strong></span> is built.
Some configuration directives may appear multiple times, others only once.
The order in which configuration directives appear within a section is not
usually significant,
although it may be in cases where the directive is repeated
(e.g., <span class="property">ACS_ERROR_HANDLER</span>)
and for clauses (e.g., the <code class="literal">Auth</code> clause).
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note12"></a>Note</h3><p>Directives that expect to be assigned a value of
<code class="literal">yes</code>, <code class="literal">no</code>,
<code class="literal">on</code>, or <code class="literal">off</code>
recognize these keywords case-insensitively.
</p></div></div><div class="refsect3"><a name="idm732"></a><h4>General Directives</h4><p>The following general directives are provided.
If present, they must appear within any <code class="literal">Default</code> section
or <code class="literal">Jurisdiction</code> section, but outside of any clauses.
</p><div class="highlights"><a name="directive_index"></a><div class="orderedlist"><p class="title"><b>Directive Index:</b></p><ol class="orderedlist compact" type="1"><li class="listitem"><p><a class="xref" href="#ACCEPT_ALIEN_CREDENTIALS">
<span class="property">ACCEPT_ALIEN_CREDENTIALS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="ACS_prefixed"></a><a class="xref" href="#ACS_ACCESS_TOKEN_ENABLE">
<span class="property">ACS_ACCESS_TOKEN_ENABLE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_ACCESS_TOKEN_LIFETIME_LIMIT">
<span class="property">ACS_ACCESS_TOKEN_LIFETIME_LIMIT</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_ACCESS_TOKEN_LIFETIME_SECS">
<span class="property">ACS_ACCESS_TOKEN_LIFETIME_SECS</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_AUTHENTICATED_ONLY">
<span class="property">ACS_AUTHENTICATED_ONLY</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_CREDENTIALS_LIMIT">
<span class="property">ACS_CREDENTIALS_LIMIT</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_EMIT_APPROVAL">
<span class="property">ACS_EMIT_APPROVAL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_ERROR_HANDLER">
<span class="property">ACS_ERROR_HANDLER</span> (Stack)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_FAIL">
<span class="property">ACS_FAIL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_INACTIVITY_LIMIT_SECS">
<span class="property">ACS_INACTIVITY_LIMIT_SECS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_POST_BUFFER_LIMIT">
<span class="property">ACS_POST_BUFFER_LIMIT</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_POST_EXCEPTION_MODE">
<span class="property">ACS_POST_EXCEPTION_MODE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_PRE_AUTH">
<span class="property">ACS_PRE_AUTH</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_SUCCESS">
<span class="property">ACS_SUCCESS</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ACS_TRACK_ACTIVITY">
<span class="property">ACS_TRACK_ACTIVITY</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ADMIN_IDENTITY">
<span class="property">ADMIN_IDENTITY</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ALLOW_HTTP_COOKIE">
<span class="property">ALLOW_HTTP_COOKIE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="AUTH_prefixed"></a><a class="xref" href="#AUTH_AGENT_ALLOW_ADMIN_IDENTITY">
<span class="property">AUTH_AGENT_ALLOW_ADMIN_IDENTITY</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS">
<span class="property">AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS</span>
(Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS">
<span class="property">AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS</span>
(Required1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_ERROR_HANDLER">
<span class="property">AUTH_ERROR_HANDLER</span> (Stack)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_FAIL">
<span class="property">AUTH_FAIL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_FAIL_DELAY_SECS">
<span class="property">AUTH_FAIL_DELAY_SECS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_SINGLE_COOKIE">
<span class="property">AUTH_SINGLE_COOKIE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_SUCCESS">
<span class="property">AUTH_SUCCESS</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_SUCCESS_HANDLER">
<span class="property">AUTH_SUCCESS_HANDLER</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_TRANSFER_EXPORT">
<span class="property">AUTH_TRANSFER_EXPORT</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#AUTH_TRANSFER_TOKEN_LIFETIME_SECS">
<span class="property">AUTH_TRANSFER_TOKEN_LIFETIME_SECS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#COMPAT_MODE">
<span class="property">COMPAT_MODE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#COOKIE_HTTPONLY">
<span class="property">COOKIE_HTTPONLY</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#COOKIE_NAME_TERMINATORS">
<span class="property">COOKIE_NAME_TERMINATORS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#COOKIE_NO_DOMAIN">
<span class="property">COOKIE_NO_DOMAIN</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#COOKIE_PATH">
<span class="property">COOKIE_PATH</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#CSS_PATH">
<span class="property">CSS_PATH</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#DTD_BASE_URL">
<span class="property">DTD_BASE_URL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#EVAL">
<span class="property">EVAL</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#FEDERATION_DOMAIN">
<span class="property">FEDERATION_DOMAIN</span> (Required1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#FEDERATION_NAME">
<span class="property">FEDERATION_NAME</span> (Required1)</a>
</p></li><li class="listitem"><p><a name="HTTP_prefixed"></a><a class="xref" href="#HTTP_AUTH">
<span class="property">HTTP_AUTH</span> (Stack)</a>
</p></li><li class="listitem"><p><a class="xref" href="#HTTP_AUTH_ENABLE">
<span class="property">HTTP_AUTH_ENABLE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#HTTP_PROG">
<span class="property">HTTP_PROG</span> (Required1)</a>
</p></li><li class="listitem"><p><a name="INFOCARD_prefixed"></a><a class="xref" href="#INFOCARD_AUDIENCE">
<span class="property">INFOCARD_AUDIENCE</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_AUDIENCE_RESTRICTION">
<span class="property">INFOCARD_AUDIENCE_RESTRICTION</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARD_DEFS_URL">
<span class="property">INFOCARD_CARD_DEFS_URL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARD_FILL_URL">
<span class="property">INFOCARD_CARD_FILL_URL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARD_IMAGE_BASE_URL">
<span class="property">INFOCARD_CARD_IMAGE_BASE_URL</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARD_LIFETIME_SECS">
<span class="property">INFOCARD_CARD_LIFETIME_SECS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARD_OUTPUTDIR">
<span class="property">INFOCARD_CARD_OUTPUTDIR</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARD_VERSION">
<span class="property">INFOCARD_CARD_VERSION</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARDID_BASE_URL">
<span class="property">INFOCARD_CARDID_BASE_URL</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARDID_SUFFIX">
<span class="property">INFOCARD_CARDID_SUFFIX</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_CARD_DATETIME_EXPIRES">
<span class="property">INFOCARD_CARD_DATETIME_EXPIRES</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_DIGEST">
<span class="property">INFOCARD_DIGEST</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_IP_PRIVACY_URL">
<span class="property">INFOCARD_IP_PRIVACY_URL</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_IP_PRIVACY_VERSION">
<span class="property">INFOCARD_IP_PRIVACY_VERSION</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_ISSUER_INFO_ENTRY">
<span class="property">INFOCARD_ISSUER_INFO_ENTRY</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_MEX_URL">
<span class="property">INFOCARD_MEX_URL</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_REQUIRE_APPLIES_TO">
<span class="property">INFOCARD_REQUIRE_APPLIES_TO</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STRONG_RP_IDENTITY">
<span class="property">INFOCARD_STRONG_RP_IDENTITY</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STS_AUTH_TYPE">
<span class="property">INFOCARD_STS_AUTH_TYPE</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STS_CACERTFILE">
<span class="property">INFOCARD_STS_CACERTFILE</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STS_CERTFILE">
<span class="property">INFOCARD_STS_CERTFILE</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STS_KEYFILE">
<span class="property">INFOCARD_STS_KEYFILE</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STS_KEYFILE_PASSWORD">
<span class="property">INFOCARD_STS_KEYFILE_PASSWORD</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STS_PASSWORD_METHOD">
<span class="property">INFOCARD_STS_PASSWORD_METHOD</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_STS_RP_ENDPOINT">
<span class="property">INFOCARD_STS_RP_ENDPOINT</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_TOKEN_DRIFT_SECS">
<span class="property">INFOCARD_TOKEN_DRIFT_SECS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_TOKEN_ISSUER">
<span class="property">INFOCARD_TOKEN_ISSUER</span> (Required1-C)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_TOKEN_LIFETIME_SECS">
<span class="property">INFOCARD_TOKEN_LIFETIME_SECS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_TOKEN_MAX_LENGTH">
<span class="property">INFOCARD_TOKEN_MAX_LENGTH</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#INFOCARD_USERNAME_SELECTOR">
<span class="property">INFOCARD_USERNAME_SELECTOR</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#JURISDICTION_NAME">
<span class="property">JURISDICTION_NAME</span> (Required1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#LOGINGEN_FILE">
<span class="property">LOGINGEN_FILE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#LOGINGEN_PROG">
<span class="property">LOGINGEN_PROG</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="LOG_prefixed"></a><a class="xref" href="#LOG_FILE">
<span class="property">LOG_FILE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#LOG_FILTER">
<span class="property">LOG_FILTER</span> (Stack)</a>
</p></li><li class="listitem"><p><a class="xref" href="#LOG_FORMAT">
<span class="property">LOG_FORMAT</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#LOG_LEVEL">
<span class="property">LOG_LEVEL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#LOG_SENSITIVE">
<span class="property">LOG_SENSITIVE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#NAME_COMPARE">
<span class="property">NAME_COMPARE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="NOTICES_prefixed"></a><a class="xref" href="#NOTICES_ACCEPT_HANDLER">
<span class="property">NOTICES_ACCEPT_HANDLER</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#NOTICES_ACK_HANDLER">
<span class="property">NOTICES_ACK_HANDLER</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#NOTICES_DECLINE_HANDLER">
<span class="property">NOTICES_DECLINE_HANDLER</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#NOTICES_NAT_NAME_PREFIX">
<span class="property">NOTICES_NAT_NAME_PREFIX</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#NOTICES_SECURE_HANDLER">
<span class="property">NOTICES_SECURE_HANDLER</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#NOTICES_WORKFLOW_LIFETIME_SECS">
<span class="property">NOTICES_WORKFLOW_LIFETIME_SECS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="PAMD_prefixed"></a><a class="xref" href="#PAMD_HOST">
<span class="property">PAMD_HOST</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PAMD_PORT">
<span class="property">PAMD_PORT</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="PASSWORD_prefixed"></a><a class="xref" href="#PASSWORD_CONSTRAINTS">
<span class="property">PASSWORD_CONSTRAINTS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PASSWORD_DIGEST">
<span class="property">PASSWORD_DIGEST</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PASSWORD_OPS_NEED_PASSWORD">
<span class="property">PASSWORD_OPS_NEED_PASSWORD</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PASSWORD_SALT_PREFIX">
<span class="property">PASSWORD_SALT_PREFIX</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PERMIT_CHAINING">
<span class="property">PERMIT_CHAINING</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="PROXY_prefixed"></a><a class="xref" href="#PROXY_EXEC_DOCUMENT_ROOT">
<span class="property">PROXY_EXEC_DOCUMENT_ROOT</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PROXY_EXEC_MAPPER_DEFAULT_ACTION">
<span class="property">PROXY_EXEC_MAPPER_DEFAULT_ACTION</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PROXY_EXEC_MAPPER_LOGGING">
<span class="property">PROXY_EXEC_MAPPER_LOGGING</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PROXY_EXEC_MAPPER_LOG_FILE">
<span class="property">PROXY_EXEC_MAPPER_LOG_FILE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PROXY_EXEC_MAPPER_RULES_FILE">
<span class="property">PROXY_EXEC_MAPPER_RULES_FILE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#PROXY_EXEC_PROG_URI">
<span class="property">PROXY_EXEC_PROG_URI</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#RLINK">
<span class="property">RLINK</span> (Optional)</a>
</p></li><li class="listitem"><p><a class="xref" href="#ROLE_STRING_MAX_LENGTH">
<span class="property">ROLE_STRING_MAX_LENGTH</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#SECURE_MODE">
<span class="property">SECURE_MODE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#SIGNOUT_HANDLER">
<span class="property">SIGNOUT_HANDLER</span> (Optional1)</a>
</p></li><li class="listitem"><p><a name="SSL_prefixed"></a><a class="xref" href="#SSL_PROG">
<span class="property">SSL_PROG</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#SSL_PROG_ARGS">
<span class="property">SSL_PROG_ARGS</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#SSL_PROG_CA_CRT">
<span class="property">SSL_PROG_CA_CRT</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#SSL_PROG_CLIENT_CRT">
<span class="property">SSL_PROG_CLIENT_CRT</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#STATUS_LINE">
<span class="property">STATUS_LINE</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#TEMP_DIRECTORY">
<span class="property">TEMP_DIRECTORY</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#TOKEN_REQUIRES_PIN">
<span class="property">TOKEN_REQUIRES_PIN</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#TOKEN_HOTP_ACCEPT_WINDOW">
<span class="property">TOKEN_HOTP_ACCEPT_WINDOW</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#TRACE_LEVEL">
<span class="property">TRACE_LEVEL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#UNAUTH_ROLES">
<span class="property">UNAUTH_ROLES</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#UPROXY_APPROVED">
<span class="property">UPROXY_APPROVED</span> (Stack)</a>
</p></li><li class="listitem"><p><a class="xref" href="#VERBOSE_LEVEL">
<span class="property">VERBOSE_LEVEL</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#VERIFY_IP">
<span class="property">VERIFY_IP</span> (Required1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#VERIFY_UA">
<span class="property">VERIFY_UA</span> (Optional1)</a>
</p></li><li class="listitem"><p><a class="xref" href="#VFS">
<span class="property">VFS</span> (Stack)</a>
</p></li><li class="listitem"><p><a class="xref" href="#XSD_BASE_URL">
<span class="property">XSD_BASE_URL</span> (Optional1)</a>
</p></li></ol></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a name="ACCEPT_ALIEN_CREDENTIALS"></a>
<span class="property">ACCEPT_ALIEN_CREDENTIALS</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>",
<span class="command"><strong>DACS</strong></span> will honour credentials imported (by any means)
from a different federation.
As a security precaution, such credentials are not used by default.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security1"></a>Security</h3><p>In federations where
<a class="ulink" href="dacs_auth_transfer.8.html" target="_top">dacs_auth_transfer(8)</a> is used,
jurisdictions will likely enable this capability.
</p></div><p>
</p></dd><dt><span class="term"><a name="ACS_ACCESS_TOKEN_ENABLE"></a>
<span class="property">ACS_ACCESS_TOKEN_ENABLE</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>",
<span class="command"><strong>ACS</strong></span>'s access token mechanism will be enabled.
By default, this feature is disabled.
Please see <a class="ulink" href="dacs_acs.8.html#authorization_caching" target="_top">Authorization Caching</a>
for details.
</p></dd><dt><span class="term"><a name="ACS_ACCESS_TOKEN_LIFETIME_LIMIT"></a>
<span class="property">ACS_ACCESS_TOKEN_LIFETIME_LIMIT</span> (Required1-C)</span></dt><dd><p>If <span class="command"><strong>ACS</strong></span>'s access token mechanism has been
enabled, this is the number of times that an access token may be used.
It must be an integer greater than zero.
There is no default value.
This value, <span class="property">ACS_ACCESS_TOKEN_LIFETIME_SECS</span>, or both
must be configured properly if the mechanism is enabled.
Because it requires updating a database entry,
this method of enforcing a limit on the lifetime of an access token
is inherently less efficient than using
<span class="property">ACS_ACCESS_TOKEN_LIFETIME_SECS</span>.
Changes to this limit do not affect access tokens that have already
been issued.
Please see <a class="ulink" href="dacs_acs.8.html#authorization_caching" target="_top">Authorization Caching</a>
for details.
</p></dd><dt><span class="term"><a name="ACS_ACCESS_TOKEN_LIFETIME_SECS"></a>
<span class="property">ACS_ACCESS_TOKEN_LIFETIME_SECS</span> (Required1-C)</span></dt><dd><p>If <span class="command"><strong>ACS</strong></span>'s access token mechanism has been
enabled, this is the lifetime in seconds of an access token,
and must be an integer greater than zero.
There is no default value.
This value, <span class="property">ACS_ACCESS_TOKEN_LIFETIME_LIMIT</span>,
or both must be configured properly if the mechanism is enabled.
Please see <a class="ulink" href="dacs_acs.8.html#authorization_caching" target="_top">Authorization Caching</a>
for details.
</p></dd><dt><span class="term"><a name="ACS_AUTHENTICATED_ONLY"></a>
<span class="property">ACS_AUTHENTICATED_ONLY</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>",
<span class="command"><strong>ACS</strong></span> will deny all requests that are not accompanied
by valid credentials, regardless of any access control rules or other
directives.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note13"></a>Note</h3><p>Since this
restriction also applies
to <span class="command"><strong>DACS</strong></span> services, if this mode is enabled
an unauthenticated user will not be able to access <span class="command"><strong>DACS</strong></span>
services by which he might authenticate himself.
Users must therefore have authenticated before this directive is enabled,
authenticate using an off-line method
(such as <a class="ulink" href="dacscookie.1.html" target="_top">dacscookie(1)</a>
or <a class="ulink" href="dacsauth.1.html" target="_top">dacsauth(1)</a>),
or authenticate at some other jurisdiction.
</p></div><p>
</p></dd><dt><span class="term"><a name="ACS_CREDENTIALS_LIMIT"></a>
<span class="property">ACS_CREDENTIALS_LIMIT</span> (Optional1)</span></dt><dd><p>The value of this directive is either
an unsigned integer greater than zero, or the keyword
"<code class="literal">none</code>" (case insensitive).
In the former case,
if a request is submitted with more than this number of valid credentials,
the request will be denied with the <code class="literal">REVOKED</code> error
(equivalent to error code <span class="errorcode">903</span>).
</p><p>Probably the most common application of this directive is to limit
each request to being associated with at most one identity.
The standard site configuration sets <span class="property">ACS_CREDENTIALS_LIMIT</span>
to one.
This eliminates confusion about which identity invoked a web service
(i.e., which identity <code class="envar">REMOTE_USER</code> should be set to,
for instance) and ambiguity regarding the semantics of rules,
and in some cases may simplify access control rules and log file audits.
</p><p>A user denied access at a jurisdiction due to this directive
will be denied access to
<a class="ulink" href="dacs_signout.8.html" target="_top">dacs_signout(8)</a> at the jurisdiction.
To regain access to the jurisdiction, the user will either need to
signout from a different jurisdiction or delete one or more sets of
credentials (cookies) from his browser,
either using the browser's cookie manager or by terminating the browser
session.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note14"></a>Note</h3><p>It is possible for a user that is not denied access at a
jurisdiction due to this directive to successfully authenticate,
after which he will have "too many" credentials and subsequently
be denied access.
Similarly, a <span class="command"><strong>DACS</strong></span> administrator may reduce the limit
at any time, potentially causing access to be denied to users holding
a number of credentials in excess of the limit.
</p></div><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security2"></a>Security</h3><p>This directive only limits the number of credentials associated
with a single request.
It does not prevent the same individual from sending different requests,
from the same browser or different browsers, each associated with a different
identity.
Also, it does not limit the number of concurrent logins of the same
identity (such as by different individuals sharing the same account).
</p><p>
<span class="command"><strong>DACS</strong></span> does not limit a user's number of concurrent logins
or the number of concurrent logins of the same identity
because of the inherent drawbacks of a general implementation
of such a feature.
In simple cases, however, an administrator may be able to add a
custom solution to <span class="command"><strong>DACS</strong></span>.
</p></div></dd><dt><span class="term"><a name="ACS_EMIT_APPROVAL"></a>
<span class="property">ACS_EMIT_APPROVAL</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>",
<span class="command"><strong>DACS</strong></span> will generate a <code class="envar">DACS_APPROVAL</code>
environment variable that can be inspected by an invoked program to
verify that its use in the current context was authorized by
<span class="command"><strong>DACS</strong></span>.
Before this feature is enabled, additional configuration is necessary;
see <a class="ulink" href="dacs_acs.8.html#dacs_approval" target="_top">The DACS_APPROVAL environment
variable</a> for details.
</p></dd><dt><span class="term"><a name="ACS_ERROR_HANDLER"></a>
<span class="property">ACS_ERROR_HANDLER</span> (Stack)</span></dt><dd><p>If <span class="command"><strong>DACS</strong></span> denies a service request,
the web server's <span class="command"><strong>DACS</strong></span> module will
be so informed and will return a
<span class="errorcode">403</span> ("<span class="errortext">Forbidden</span>")
status code to the web server.
By using <span class="command"><strong>Apache's</strong></span> <span class="property">ErrorDocument</span>
directive, the resulting action taken by
<span class="command"><strong>Apache</strong></span> can be customized.
</p><p>In some situations following denial of a request, however,
it is desirable to initiate an action that depends on the reason for denial.
For example, if access is denied because the user is not authenticated, the
<span class="command"><strong>DACS</strong></span> administrator might want users to be
redirected to a login page; if access is denied because an access
control rule denies access although the user is authenticated,
the administrator might want users to be redirected to a page that
displays a custom error message.
It is sometimes useful for the action to depend on the resource being
requested.
</p><p>The <span class="property">ACS_ERROR_HANDLER</span> directive defines
(or overrides) <span class="command"><strong>Apache</strong></span>'s behaviour with respect to an
<span class="property">ErrorDocument</span> directive for
<span class="errorcode">403</span> errors if <span class="command"><strong>DACS</strong></span> denies a
service request.
The syntax and meaning of this directive are similar to that of
<span class="command"><strong>Apache</strong></span>'s <span class="property">ErrorDocument</span> directive.
Please refer to the <span class="command"><strong>Apache</strong></span> documentation for a
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/core.html#errordocument" target="_top">description of the <span class="property">ErrorDocument</span> directive</a>.
</p><p>Also refer to the description of the
<a class="ulink" href="dacs.exprs.5.html#redirect" target="_top">redirect()</a>
function.
</p><p>The syntax of the directive is:
</p><pre class="screen">
[<em class="replaceable"><code>url_pattern</code></em>] <em class="replaceable"><code>error-code</code></em> [<em class="replaceable"><code>handler-type</code></em>] [<em class="replaceable"><code>error-action</code></em>]
</pre><p>
</p><p>The optional <em class="replaceable"><code>url_pattern</code></em> is a URI path
component that is matched against the request for which access was denied.
It must begin with a '<code class="literal">/</code>'.
It is like the <em class="replaceable"><code>url_pattern</code></em> used in
<a class="ulink" href="dacs.acls.5.html#elements" target="_top">access control rules</a>
in that it can require an exact match or end in
"<span class="path">/*</span>";
no query argument component is allowed.
If it is absent, the <em class="replaceable"><code>url_pattern</code></em> defaults to
"<code class="literal">/*</code>", which matches any path.
</p><p>The <em class="replaceable"><code>error-code</code></em> is either a numeric
error code, an equivalent case-insensitive
<em class="replaceable"><code>error-name</code></em>,
or the special symbol "<code class="literal">*</code>", which means the directive
applies to any <span class="command"><strong>DACS</strong></span> error code for which there is no
explicit directive.
</p><p>The following <em class="replaceable"><code>error-name</code></em> and
<em class="replaceable"><code>error-code</code></em> values are defined:
</p><div class="variablelist"><dl class="variablelist"><dt><a name="errorname_NO_RULE"></a><span class="term"><a name="errorcode_900"></a><span class="errorname">NO_RULE</span> (<span class="errorcode">900</span>)
<br></span><span class="term"><span class="errortext">Access denied, no applicable rule</span>
</span></dt><dd><p>All rules were examined but no rule applies to the
service request.
</p></dd><dt><a name="errorname_BY_RULE"></a><span class="term"><a name="errorcode_901"></a><span class="errorname">BY_RULE</span> (<span class="errorcode">901</span>)
<br></span><span class="term"><span class="errortext">Access denied, forbidden by rule</span>
</span></dt><dd><p>The closest matching rule does not grant the service request.
</p></dd><dt><a name="errorname_NO_AUTH"></a><span class="term"><a name="errorcode_902"></a><span class="errorname">NO_AUTH</span> (<span class="errorcode">902</span>)
<br></span><span class="term"><span class="errortext">Access denied, user not authenticated</span>
</span></dt><dd><p>No valid credentials were provided and either a) no rule
applies or b) the rule does not grant the service request.
</p></dd><dt><a name="errorname_REVOKED"></a><span class="term"><a name="errorcode_903"></a><span class="errorname">REVOKED</span> (<span class="errorcode">903</span>)
<br></span><span class="term"><span class="errortext">Access denied, user access revoked</span>
</span></dt><dd><p>Credentials were explicitly revoked.
</p></dd><dt><a name="errorname_BY_REDIRECT"></a><span class="term"><a name="errorcode_904"></a><span class="errorname">BY_REDIRECT</span> (<span class="errorcode">904</span>)
<br></span><span class="term"><span class="errortext">Access denied, redirect</span>
</span></dt><dd><p>A rule has explicitly redirected the user.
</p></dd><dt><a name="errorname_ACK_NEEDED"></a><span class="term"><a name="errorcode_905"></a><span class="errorname">ACK_NEEDED</span> (<span class="errorcode">905</span>)
<br></span><span class="term"><span class="errortext">Access denied, acknowledgement needed</span>
</span></dt><dd><p>One or more notices associated with the request must
be acknowledged.
</p></dd><dt><a name="errorname_LOW_AUTH"></a><span class="term"><a name="errorcode_906"></a><span class="errorname">LOW_AUTH</span> (<span class="errorcode">906</span>)
<br></span><span class="term"><span class="errortext">Access denied, low authentication level</span>
</span></dt><dd><p>Although valid credentials were provided, they were
obtained by an authentication method not strong enough for the
requested resource.
</p></dd><dt><a name="errorname_BY_SIMPLE_REDIRECT"></a><span class="term"><a name="errorcode_907"></a><span class="errorname">BY_SIMPLE_REDIRECT</span> (<span class="errorcode">907</span>)
<br></span><span class="term"><span class="errortext">Access denied, simple redirect</span>
</span></dt><dd><p>A rule has explicitly redirected the user; do not
append <span class="command"><strong>DACS</strong></span> query arguments.
</p></dd><dt><a name="errorname_CREDENTIALS_LIMIT"></a><span class="term"><a name="errorcode_908"></a><span class="errorname">CREDENTIALS_LIMIT</span> (<span class="errorcode">908</span>)
<br></span><span class="term"><span class="errortext">Access denied, too many credentials were submitted</span>
</span></dt><dd><p>Too many selected credentials accompanied the request.
</p></dd><dt><a name="errorname_INACTIVITY"></a><span class="term"><a name="errorcode_909"></a><span class="errorname">INACTIVITY</span> (<span class="errorcode">909</span>)
<br></span><span class="term"><span class="errortext">Access denied, inactivity timeout</span>
</span></dt><dd><p>No authenticated requests were made within a designated
time interval.
</p></dd><dt><a name="errorname_ADMIN_REQUIRED"></a><span class="term"><a name="errorcode_910"></a><span class="errorname">ADMIN_REQUIRED</span> (<span class="errorcode">910</span>)
<br></span><span class="term"><span class="errortext">Access denied, administrator credentials required</span>
</span></dt><dd><p>Access was denied because credentials that satisfy
<a class="ulink" href="dacs.exprs.5.html#dacs_admin" target="_top">dacs_admin()</a>
were not sent with the request.
Although this may not be the sole reason for access to be denied,
it should be taken as a hint that the request is likely to succeed if
it is retried with administrator credentials.
Also see
<a class="ulink" href="#ADMIN_IDENTITY" target="_top">ADMIN_IDENTITY</a>.
</p></dd><dt><a name="errorname_UNKNOWN"></a><span class="term"><a name="errorcode_998"></a><span class="errorname">UNKNOWN</span> (<span class="errorcode">998</span>)
<br></span><span class="term"><span class="errortext">Access denied, reason unknown</span>
</span></dt><dd><p>An error occurred during processing but no additional
information is available.
</p></dd><dt><a name="errorname_DEFAULT"></a><span class="term"><code class="literal">DEFAULT</code> (<code class="literal">*</code>)
<br></span><span class="term">Control symbol</span></dt><dd><p>Not an error name, but a keyword
used with <span class="property">ACS_ERROR_HANDLER</span> to configure a handler to
invoke if no handler is explicitly configured for the event.
</p></dd></dl></div><p>
</p><p>No blanks may precede the code, any number of blanks
may follow it. The descriptive-text consists only of printable characters
(e.g., no tabs or newlines) and may not contain a colon. The
descriptive-text is subject to change, but the meaning of the code number
is fixed.
When <span class="command"><strong>DACS</strong></span> returns a numeric error code,
a program only needs to examine the three digit code to determine why
access was denied.
Optionally, the standard text may be followed by a single space,
a colon, at least one space, and a more detailed error message.
</p><p>If a <em class="replaceable"><code>handler-type</code></em> keyword appears,
it selects the action the handler should take and disables
the heuristics that would otherwise be used to decide the type
based on the syntax of the <em class="replaceable"><code>error-action</code></em>.
The <code class="literal">reason</code> and <code class="literal">default</code> keywords
are the only <em class="replaceable"><code>handler-type</code></em> keyword that are
not followed by an <em class="replaceable"><code>error-action</code></em>.
</p><p>The following <em class="replaceable"><code>handler-type</code></em> keywords
and <em class="replaceable"><code>error-action</code></em> arguments are recognized:
</p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p><code class="literal">reason</code></p><p><span class="command"><strong>DACS</strong></span> will cause <span class="command"><strong>Apache</strong></span>
to display the <span class="command"><strong>DACS</strong></span> error code that identifies
the reason for denying access followed by the corresponding textual
message.
<span class="command"><strong>Apache</strong></span> might display messages like the following:
</p><pre class="programlisting">
900 Access denied, no applicable access control rule
998 Access denied, internal error: Cookie parse error
</pre><p>
</p></li><li class="listitem"><p><code class="literal">default</code>
</p><p>This form instructs <span class="command"><strong>DACS</strong></span> not to alter
<span class="command"><strong>Apache's</strong></span> behaviour
(as if there was no <span class="property">ACS_ERROR_HANDLER</span> specified at all).
</p></li><li class="listitem"><p>[<code class="literal">url</code>] <em class="replaceable"><code>URL</code></em>
</p><p>This form will cause <span class="command"><strong>Apache</strong></span> to redirect the client to
<em class="replaceable"><code>URL</code></em> using the <code class="literal">GET</code> method.
If the <code class="literal">url</code> keyword is absent,
<em class="replaceable"><code>URL</code></em> must begin with the four characters
"<code class="literal">http</code>".
An invalid <em class="replaceable"><code>URL</code></em> may be rejected by Apache
and treated as a message.
The <em class="replaceable"><code>URL</code></em> may contain a properly escaped query string;
<span class="command"><strong>DACS</strong></span> will append
the following parameters, in the order given, to <em class="replaceable"><code>URL</code></em>
(unless the error name is <code class="literal">BY_SIMPLE_REDIRECT</code>,
in which case none of these parameters is passed):
</p><div class="orderedlist"><ol class="orderedlist" type="A"><li class="listitem"><p><em class="parameter"><code>DACS_ERROR_CODE</code></em>,
the <span class="command"><strong>DACS</strong></span> error code.</p></li><li class="listitem"><p><em class="parameter"><code>DACS_VERSION</code></em>,
the version number of <span class="command"><strong>DACS</strong></span>
(e.g., "<code class="literal">1.4</code>").</p></li><li class="listitem"><p><em class="parameter"><code>DACS_FEDERATION</code></em>,
the federation that received the service request,
if available.</p></li><li class="listitem"><p><em class="parameter"><code>DACS_JURISDICTION</code></em>,
the jurisdiction that received the service request, if
available.</p></li><li class="listitem"><p><em class="parameter"><code>DACS_HOSTNAME</code></em>,
the domain name of the host that received the service request, if
available.</p></li><li class="listitem"><p><em class="parameter"><code>DACS_USER_AGENT</code></em>,
if provided by the user agent, this is an identifying string, such as:
</p><pre class="programlisting">
Mozilla/3.01 (X11; U; Linux 2.4.2 i386)
</pre><p>
</p></li><li class="listitem"><p><em class="parameter"><code>DACS_REQUEST_METHOD</code></em>,
the method used to invoke the service request, if available.
For example, "<code class="literal">GET</code>" or "<code class="literal">POST</code>".
</p></li><li class="listitem"><p><em class="parameter"><code>DACS_ERROR_URL</code></em>,
the service request URL, including any query string component.
The values of these parameters are URL encoded.</p></li></ol></div></li><li class="listitem"><p>[<code class="literal">localurl</code>] <code class="literal">/</code><em class="replaceable"><code>local-URL</code></em>
</p><p>This form is similar to the absolute URL form except that redirection
is to a local URL-path.
The <em class="replaceable"><code>error-action</code></em> must begin with a slash.
The URL may contain a properly escaped query string;
<span class="command"><strong>DACS</strong></span> will append additional parameters as in the
absolute URL form.
</p></li><li class="listitem"><p>[<code class="literal">message</code>] \"<em class="replaceable"><code>a message</code></em>\"
</p><p>This form causes <span class="command"><strong>Apache</strong></span> to emit the given
string as the error document.
If the <code class="literal">message</code> keyword is absent,
the string must be surrounded by double quote characters
(the quotes do not appear in the final output message).
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note15"></a>Note</h3><p>Apache always sets the <span class="property">Content-Type</span>
for this message to <code class="literal">text/html</code>.
Although reported quite some time ago,
<a class="ulink" href="http://issues.apache.org/bugzilla/show_bug.cgi?id=36411" target="_top">Bug 3641</a>
is still open.
There may be a bug in Apache 2.X that prevents the initial double quote
in the message from being stripped; see
<a class="ulink" href="http://issues.apache.org/bugzilla/show_bug.cgi?id=42430" target="_top">Bug 42430</a>.
</p></div><p>
</p></li><li class="listitem"><p><code class="literal">expr</code> <em class="replaceable"><code>expression</code></em>
</p><p>The <code class="literal">expr</code> keyword, which cannot be omitted,
indicates that the <em class="replaceable"><code>error-action</code></em> is an expression.
The <em class="replaceable"><code>expression</code></em> is evaluated and its value
(a string) is used as the Apache error response.
If an error occurs during evaluation, the Apache
<span class="property">ErrorDocument</span> or default behaviour will be used.
</p></li></ol></div><p>
</p><p>This directive may appear multiple times.
Because these directives are stacked, during handler processing directives
are examined "backwards", starting from the last one that appears in
the relevant jurisdiction section through to the first one that appears in
the default section of <code class="filename">dacs.conf</code> and backwards through
<code class="filename">site.conf</code>.
The first directive having a <em class="replaceable"><code>url_pattern</code></em>
<span class="emphasis"><em>and</em></span> <em class="replaceable"><code>error-code</code></em> that match
the error condition exactly is used.
Otherwise, if no such exact match if found, the first directive encountered
having the closest <em class="replaceable"><code>url_pattern</code></em> match and exact
<em class="replaceable"><code>error-code</code></em> match is used;
failing that, the first directive with the closest
<em class="replaceable"><code>url_pattern</code></em> match and default
("<code class="literal">*</code>") <em class="replaceable"><code>error-code</code></em> match is used.
</p><p>Consider these example directives:
</p><pre class="screen">
ACS_ERROR_HANDLER "* reason"
ACS_ERROR_HANDLER '903 "Your access has been revoked"'
ACS_ERROR_HANDLER "/foo/* * /cgi-bin/dacs/foohandler"
ACS_ERROR_HANDLER "/foo/foo.html NO_AUTH /cgi-bin/foo-login.cgi"
</pre><p>
A request for <span class="path">/foo/foo.html</span>
that is denied because the user is not authenticated will cause a redirect to
<span class="path">/cgi-bin/foo-login.cgi</span>.
If the request is denied for a different reason, the third directive
will be used, causing a redirect to
<span class="path">/cgi-bin/dacs/foohandler</span>.
A request for something not located under
<span class="path">/foo</span> that is denied because access
is revoked will cause
the message specified in the second directive to be displayed to the user,
while any other type of error will cause an appropriate explanatory message
to be displayed.
</p><p>Here is an example of the <code class="literal">expr</code> handler form:
</p><pre class="screen">
ACS_ERROR_HANDLER "* expr '\"&lt;em>Today is&lt;/em> \" . strftime(\"%D\")'"
</pre><p>
If triggered, this directive will emit a message similar to the
following as Apache's custom error response:
</p><pre class="screen">
<em>Today is</em> 05/16/07
</pre><p>
As with all such messages, Apache forces the <span class="property">Content-Type</span>
to be <code class="literal">text/html</code>.
</p><p>These two directives are equivalent:
</p><pre class="screen">
ACS_ERROR_HANDLER "* message 'Hello world.'"
ACS_ERROR_HANDLER "* \"Hello world.\""
</pre><p>
The error response returned by Apache will be:
</p><pre class="screen">
Hello world.
</pre><p>
</p><p>Any invalid directive will result
in <span class="command"><strong>Apache</strong></span> following its configured behaviour.
A directive with a syntactically valid but undefined
<em class="replaceable"><code>error-code</code></em> is ignored, however.
</p><p>In the case where the service request was issued by
<span class="command"><strong>Internet Explorer</strong></span>,
if the length of the error response by the server isn't greater than some
magic value and <span class="command"><strong>IE</strong></span>'s
"<code class="literal">Show friendly HTTP error messages</code>" is enabled,
which it is by default, then <span class="command"><strong>IE</strong></span>
will ignore the custom message.
When the "message" and "reason" handler types are used,
<span class="command"><strong>DACS</strong></span> adds some padding to thwart
<span class="command"><strong>IE</strong></span>'s "cleverness".
For other handler types, the administrator is responsible for
working around this problem.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note16"></a>Note</h3><p>Care must be taken
to avoid improper operation (such as a
potentially infinite regress) if a CGI program invoked to handle an error is
itself protected by <span class="command"><strong>DACS</strong></span>.
One example is the situation where a user's access
has been revoked and is therefore unable to access any
<span class="command"><strong>DACS</strong></span>-protected resource.
If an error occurs while <span class="command"><strong>DACS</strong></span> is processing a request
for a handler, <span class="command"><strong>DACS</strong></span> will fall back to
<span class="command"><strong>Apache</strong></span>'s default behaviour, ignoring any normally
applicable <span class="property">ACS_ERROR_HANDLER</span> directives.
</p></div></dd><dt><span class="term"><a name="ACS_FAIL"></a>
<span class="property">ACS_FAIL</span> (Optional1)</span></dt><dd><p>If <span class="command"><strong>dacs_acs</strong></span> denies access,
the given expression is evaluated just before the
<a class="ulink" href="#ACS_ERROR_HANDLER" target="_top">ACS_ERROR_HANDLER</a> directive,
if any, is processed.
This directive provides a hook for post-authorization actions to be
performed.
The namespaces in effect during authorization processing are
accessible to the expression.
The value of the expression is discarded and any errors are ignored.
</p></dd><dt><span class="term"><a name="ACS_INACTIVITY_LIMIT_SECS"></a>
<span class="property">ACS_INACTIVITY_LIMIT_SECS</span> (Optional1)</span></dt><dd><p>This directive enables inactivity detection if it is
set to a non-zero unsigned integer.
Inactivity detection is applicable only when valid selected credentials
accompany a request
(i.e., at least one identity is associated with the request - see
<a class="ulink" href="dacs_select_credentials.8.html" target="_top">dacs_select_credentials(8)</a>).
</p><p>There are two cases.
If an activity tracking cookie is not sent with the current request
(see <a class="ulink" href="#ACS_TRACK_ACTIVITY" target="_top">ACS_TRACK_ACTIVITY</a>),
the user is deemed to be inactive if the newest
credentials are older than <span class="property">ACS_INACTIVITY_LIMIT_SECS</span>
seconds.
If an activity tracking cookie is received,
the user is deemed to be inactive if the date/time that it asserts
is older than <span class="property">ACS_INACTIVITY_LIMIT_SECS</span> seconds.
If inactivity is detected by
<a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a>,
access is denied and
an <span class="errorname">INACTIVITY</span> error (<span class="errorcode">909</span>)
is raised;
see <a class="ulink" href="#ACS_ERROR_HANDLER" target="_top">ACS_ERROR_HANDLER</a>.
At present, the only way for a user to continue after an inactivity
error is to explicitly delete <span class="command"><strong>DACS</strong></span> cookies or
implicitly delete them by restarting the browser.
A non-<span class="command"><strong>DACS</strong></span>-wrapped web page or CGI program might be
invoked as an error handler to assist.
</p><p>Different jurisdictions may independently configure different inactivity
thresholds, disable inactivity detection, or disable activity
tracking - the degree to which this feature improves security or is
annoying to users depends on thoughtful cooperation amongst jurisdictions
and adequate clock synchronization.
</p></dd><dt><span class="term"><a name="ACS_POST_BUFFER_LIMIT"></a>
<span class="property">ACS_POST_BUFFER_LIMIT</span> (Optional1)</span></dt><dd><p>This is the counterpart to the
<a class="ulink" href="mod_auth_dacs.html#SetDACSAuthPostBuffer" target="_top">SetDACSAuthPostBuffer</a>
directive of <span class="command"><strong>DACS's</strong></span>
<a class="ulink" href="mod_auth_dacs.html" target="_top">mod_auth_dacs</a>
<span class="command"><strong>Apache</strong></span> module.
It establishes the maximum number of bytes of environment and
<code class="literal">POST</code> stream that <span class="command"><strong>DACS</strong></span> should read from
<a class="ulink" href="mod_auth_dacs.html" target="_top">mod_auth_dacs</a>,
overriding the compile-time default.
To allow for encoding overhead when serializing the message body,
<span class="property">ACS_POST_BUFFER_LIMIT</span>
should be at least 50% larger than the
<span class="property">SetDACSAuthPostBuffer</span> size.
A value of zero imposes no limit.
(Ideally, only one of these values would need to be configured but
you must currently ensure that both of them are set to reasonable values.)
</p></dd><dt><span class="term"><a name="ACS_POST_EXCEPTION_MODE"></a>
<span class="property">ACS_POST_EXCEPTION_MODE</span> (Optional1)</span></dt><dd><p>In the event that the web server has not made all of
the request's arguments available to <span class="command"><strong>DACS</strong></span> for
access control processing
(see
<a class="ulink" href="dacs_acs.8.html#SERVICE_ARGS_TRUNCATED" target="_top">SERVICE_ARGS_TRUNCATED</a>),
this directive tells <a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a>
what to do.
The following keywords are recognized values:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">abort</code></span></dt><dd><p>Access control processing stops and access is denied.
</p></dd><dt><span class="term"><code class="literal">default</code></span></dt><dd><p>This is equivalent to <code class="literal">discard</code>.
</p></dd><dt><span class="term"><code class="literal">discard</code></span></dt><dd><p>Processing continues, but all web service arguments are
ignored and none will be available to access control rules.
</p></dd><dt><span class="term"><code class="literal">proceed</code></span></dt><dd><p>Continue processing, even though one or more arguments may be
corrupted or missing.
This may result in a segmentation fault or other unrecoverable error.
</p></dd><dt><span class="term"><code class="literal">query</code></span></dt><dd><p>Continue processing, discarding all POST arguments but including
any arguments that were passed in the request URI's query component.
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><a name="ACS_PRE_AUTH"></a>
<span class="property">ACS_PRE_AUTH</span> (Optional)</span></dt><dd><p>Similar to the pre-authorization authentication
feature configured through the <a class="ulink" href="#HTTP_AUTH" target="_top">HTTP_AUTH</a>
directive,
this directive provides a way to authenticate - or identify - a user at
access control time.
Rather than involving HTTP Basic or Digest authentication, however,
the value of the directive is an expression that is evaluated.
If the result is a
<a class="ulink" href="dacs.1.html#dacs_identity" target="_top">syntactically valid username</a>,
credentials are created that (normally) exist only for the duration of the
authorization check and which are associated with the
<a class="ulink" href="dacs.1.html#current_jurisdiction" target="_top">current jurisdiction</a>.
This directive provides a hook for associating an identity with a request
<span class="emphasis"><em>based on the request itself</em></span>
(such as the request URI, its arguments, and other context).
</p><p>As a simple example, the following directive checks if the request
includes a <em class="parameter"><code>USERNAME</code></em> argument, and if so, just uses it:
</p><pre class="screen">
ACS_PRE_AUTH '${Args::USERNAME:e} ? ${Args::USERNAME} : ""'
</pre><p>
Note the single quotes around the expression so that it is evaluated at
access control time instead of configuration processing time.
</p><p>The <span class="property">ACS_PRE_AUTH</span> directives are processed
if a request is received that does not include valid credentials
and if not disabled by
<a class="ulink" href="#ACS_AUTHENTICATED_ONLY" target="_top">ACS_AUTHENTICATED_ONLY</a>.
If more than one <span class="property">ACS_PRE_AUTH</span> directive is given,
they are evaluated in the order in which they appear until one
returns a valid username.
If that expression sets the variable
<code class="varname"><a name="var_auth_roles"></a>${Auth::ROLES}</code> to a valid role string,
it will be included in the credentials (see
<a class="ulink" href="dacs_authenticate.8.html#Roles" target="_top">dacs_authenticate(8)</a>).
Evaluation errors are ignored.
If no expression returns a valid username,
access control processing continues.
</p><p>These directives are processed before any
<span class="property">HTTP_AUTH</span> directives;
if a <span class="property">ACS_PRE_AUTH</span> directive is successful,
the user will effectively be authenticated and so no
<span class="property">HTTP_AUTH</span> directives will be processed.
</p><p>If the request includes a <code class="option">-rname</code> flag
with the <a class="ulink" href="dacs_acs.8.html#dacs_acs_argument" target="_top">DACS_ACS</a>
argument, its value is
<code class="varname"><a name="var_args_rname"></a>${Args::RNAME}</code>.
</p><p>Unlike when authentication is done through
<a class="ulink" href="dacs_authenticate.8.html" target="_top">dacs_authenticate(8)</a>,
<span class="emphasis"><em>credentials are not returned to the client</em></span>.
This means that no <span class="command"><strong>DACS</strong></span> session state exists outside
of <span class="command"><strong>dacs_acs</strong></span> and therefore some <span class="command"><strong>DACS</strong></span>
web services may be unavailable or may not operate in the same way
they would if credentials were provided by the client.
This mechanism may also be less efficient than one that returns credentials
because authentication will be performed each and every time the client
makes a request that triggers it.
</p></dd><dt><span class="term"><a name="ACS_SUCCESS"></a>
<span class="property">ACS_SUCCESS</span> (Optional)</span></dt><dd><p>If <span class="command"><strong>dacs_acs</strong></span> grants access,
immediately before it terminates it evaluates the given expression.
This directive provides a hook for post-authorization actions to be
performed, which can be user-specific.
The namespaces in effect during authorization processing are
accessible to the expression.
The value of the expression is discarded and any errors are ignored.
</p><p>Also see the
<a class="ulink" href="dacs.exprs.5.html#on_success" target="_top">on_success()</a> function.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note17"></a>Note</h3><p>While
it is typically true that if
<span class="command"><strong>DACS</strong></span> grants a request, the web server
will go on to process the request
(and eventually return a web page to the user agent, execute a program, etc.),
it is not necessarily so.
For example,
access may still be denied by the web server for other reasons,
or an error can occur during subsequent processing.
This may be relevant in situations where <span class="property">ACS_SUCCESS</span>
is used to decrement a <a class="ulink" href="dacs.exprs.5.html#counter" target="_top">counter</a>,
for instance, because it is possible that the user may not actually
see a successful result, in which case the counter value should not have
been changed and so corrective action would be required.
</p></div></dd><dt><span class="term"><a name="ACS_TRACK_ACTIVITY"></a>
<span class="property">ACS_TRACK_ACTIVITY</span> (Optional1)</span></dt><dd><p>This directive is associated with the
inactivity timeout feature whereby an authenticated user is denied
access (at any jurisdiction where it is enabled within the
<a class="ulink" href="dacs.1.html#current_federation" target="_top">current federation</a>)
if no web service request is made within a certain time period
(also at any jurisdiction where it is enabled within the
<a class="ulink" href="dacs.1.html#current_federation" target="_top">current federation</a>).
See
<a class="ulink" href="#ACS_INACTIVITY_LIMIT_SECS" target="_top">ACS_INACTIVITY_LIMIT_SECS</a>.
This feature is disabled by default.
It is enabled on a per-jurisdiction basis,
and in the usual configuration all jurisdictions within a federation will
enable the feature if it is required.
</p><p>If the directive's value is "<code class="literal">yes</code>",
<a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a> emits
a federation-wide HTTP cookie that notes the jurisdiction and date/time
at which each <span class="command"><strong>DACS</strong></span>-wrapped service request is processed.
The cookie is emitted regardless of whether access was granted,
although some error conditions may prevent a cookie from being sent.
No cookie is set for an effectively unauthenticated request.
</p><p>The name of the activity tracking cookie has the following format:
</p><pre class="programlisting">
DACS:<em class="replaceable"><code>federation-name</code></em>::::ACTIVITY
</pre><p>
where <em class="replaceable"><code>federation-name</code></em> is the official name
assigned to the federation for which the cookie is valid
(<a class="ulink" href="#FEDERATION_NAME" target="_top">FEDERATION_NAME</a>).
Activity tracking may be enabled without enabling inactivity detection
(via
<a class="ulink" href="#ACS_INACTIVITY_LIMIT_SECS" target="_top">ACS_INACTIVITY_LIMIT_SECS</a>).
This feature depends on an appropriate level of clock synchronization
at all participating jurisdictions.
</p></dd><dt><span class="term"><a name="ADMIN_IDENTITY"></a>
<span class="property">ADMIN_IDENTITY</span> (Optional)</span></dt><dd><p>This repeatable directive specifies a <span class="command"><strong>DACS</strong></span>
identity (group names are currently not allowed)
that <span class="command"><strong>DACS</strong></span> grants special privileges.
If omitted, the
<a class="ulink" href="dacs.1.html#current_federation" target="_top">current federation and jurisdiction</a>
are implied.
The usernames "<code class="literal">unauth</code>" and
"<code class="literal">unauthenticated</code>" are disallowed,
whether qualified with a jurisdiction or not.
The function
<a class="ulink" href="dacs.exprs.5.html#dacs_admin" target="_top">dacs_admin()</a>
tests whether the user making a service request has any credentials that
match any <span class="property">ADMIN_IDENTITY</span>.
This enables boilerplate access control rules to be written
that need to restrict access to an administrator - the rules need
only invoke <code class="function">dacs_admin()</code>.
Changes to the list of <span class="command"><strong>DACS</strong></span> administrators take
effect immediately.
Comparison of these identities with credentials is controlled by the
<a class="ulink" href="#NAME_COMPARE" target="_top">NAME_COMPARE</a> directive.
</p><p>Some <span class="command"><strong>DACS</strong></span> services call an internal version
of this function to ensure certain operations are limited to
a <span class="command"><strong>DACS</strong></span> administrator.
</p></dd><dt><span class="term"><a name="ALLOW_HTTP_COOKIE"></a>
<span class="property">ALLOW_HTTP_COOKIE</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>",
<span class="command"><strong>DACS</strong></span> components will allow the environment variable
<code class="envar">HTTP_COOKIE</code> to be used to pass <span class="command"><strong>DACS</strong></span>
credentials. This is currently
necessary when <span class="command"><strong>DACS</strong></span> components are invoked through
IIS (except in
conjunction with <span class="command"><strong>DACS</strong></span> proxied operation).
On secure systems, this method of
passing credentials may be acceptable, but in general it is not secure and
must not be allowed because environment variables are essentially public
on some systems. If undefined or not "<code class="literal">yes</code>",
<span class="command"><strong>DACS</strong></span>
components will fail if <code class="envar">HTTP_COOKIE</code> is present.
</p></dd><dt><span class="term"><a name="AUTH_AGENT_ALLOW_ADMIN_IDENTITY"></a>
<span class="property">AUTH_AGENT_ALLOW_ADMIN_IDENTITY</span> (Optional1)</span></dt><dd><p>Unless this directive has the value "<code class="literal">yes</code>",
<span class="command"><strong>dacs_auth_agent</strong></span> will not return
credentials that have been designated as an
<span class="property">ADMIN_IDENTITY</span>.
</p></dd><dt><span class="term"><a name="AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS"></a>
<span class="property">AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS</span>
(Optional1)</span></dt><dd><p>The lifetime, in seconds, of all credentials
created by this jurisdiction for internal use.
These credentials are used in certain internal transactions,
such as when <span class="command"><strong>dacs_authenticate</strong></span> sends an HTTP request
to an authentication or roles module.
Although they are only supposed to be held by trusted components, because
these credentials can convey special privileges their lifetime should not be
much longer than required.
It is sometimes necessary to increase this lifetime when debugging or if
a recipient server is slow.
</p></dd><dt><span class="term"><a name="AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS"></a>
<span class="property">AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS</span>
(Required1)</span></dt><dd><p>The default lifetime, in seconds, of all credentials
created by this jurisdiction for users.
The jurisdiction's authentication services may override this
value on a case-by-case basis,
either through an authentication module
(see <a class="ulink" href="../dtd-xsd/auth_reply.dtd" target="_top">auth_reply.dtd</a>)
or by setting
<code class="varname"><a name="var_auth_credentials_lifetime_secs"></a>${Auth::CREDENTIALS_LIFETIME_SECS}</code>
(see <a class="ulink" href="dacs_authenticate.8.html" target="_top">dacs_authenticate(8)</a>).
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security3"></a>Security</h3><p>The lifetime should be chosen such that it strikes a balance between
security and user convenience that is appropriate for the jurisdiction
and federation.
</p></div></dd><dt><span class="term"><a name="AUTH_ERROR_HANDLER"></a>
<span class="property">AUTH_ERROR_HANDLER</span> (Stack)</span></dt><dd><p>If <a class="ulink" href="dacs_authenticate.8.html" target="_top">dacs_authenticate(8)</a>
is not able to successfully authenticate a user, the
resulting action can be customized in ways that depend on the reason for
the failure. This provides a way for the system administrator to display
a custom error message or redirect the user's browser.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note18"></a>Note</h3><p>This feature is activated only if
<span class="command"><strong>dacs_authenticate</strong></span> is passed
an <em class="parameter"><code>ENABLE_AUTH_HANDLERS</code></em>
parameter that has a value of <code class="literal">1</code>.
</p></div><p>The following error code numbers and
corresponding descriptive text are defined:
</p><pre class="programlisting">
800 Authentication failed, invalid authenticating information
801 Authentication failed, invalid argument
802 Authentication failed, internal error
899 Authentication failed, reason unknown
</pre><p>
</p><p>When this type of response is returned,
a program needs to only examine the three digit code to determine why
access was denied. No blanks may precede the code, any number of blanks
may follow it. The descriptive-text consists only of printable characters
(e.g., no tabs or newlines) and may not contain a colon. The
descriptive-text is subject to change, but the meaning of the code number
is fixed. Optionally, the standard text may be followed by a single space,
a colon, at least one space, and a more detailed error message.
</p><p>The <span class="command"><strong>dacs_authenticate</strong></span> service recognizes a
<em class="parameter"><code>FORMAT</code></em> argument that is used to
select between an XML-aware user agent
(<code class="literal">FORMAT=XML</code>) and an HTML capable user
agent (<em class="parameter"><code>FORMAT</code></em>
is not specified or is not XML). In the case of an XML result,
<a class="ulink" href="../dtd-xsd/dacs_auth_reply.dtd" target="_top">dacs_auth_reply.dtd</a>
is used. The behaviour of this directive with
respect to <em class="parameter"><code>FORMAT</code></em>
is described below on a case-by-case basis.
</p><p>The following directives are supported:
</p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p><code class="literal"><span class="property">AUTH_ERROR_HANDLER</span>
"<em class="replaceable"><code>AUTH-error-code</code></em> reason"</code>
</p><p><span class="command"><strong>DACS</strong></span> will return an HTML
(or XML, if <code class="literal">FORMAT=XML</code>) document that
describes why authentication failed, such as the following:
</p><pre class="programlisting">
800 Authentication failed, invalid authenticating information
</pre><p>
This is the default behaviour.
</p></li><li class="listitem"><p><code class="literal"><span class="property">AUTH_ERROR_HANDLER</span>
"<em class="replaceable"><code>AUTH-error-code</code></em> [url] <em class="replaceable"><code>URL</code></em>"</code>
</p><p>This form causes
<span class="command"><strong>DACS</strong></span> to redirect the client to the specified URL,
which may be a relative or absolute URL.
If the keyword <code class="literal">url</code> is absent,
<em class="replaceable"><code>URL</code></em>
must begin with the four characters <code class="literal">http</code>.
The <code class="literal">GET</code> method will be used.
The URL may contain a properly escaped query string;
<span class="command"><strong>DACS</strong></span> will append
the following parameters, in the order given, to the URL:
</p><div class="orderedlist"><ol class="orderedlist" type="A"><li class="listitem"><p><em class="parameter"><code>DACS_ERROR_CODE</code></em>,
the AUTH-error-code that identifies the failure.
</p></li><li class="listitem"><p><em class="parameter"><code>DACS_VERSION</code></em>,
the version number of <span class="command"><strong>DACS</strong></span>
(e.g., "<code class="literal">1.4</code>").
</p></li><li class="listitem"><p><em class="parameter"><code>DACS_FEDERATION</code></em>,
the federation that received the service request, if available.
</p></li><li class="listitem"><p><em class="parameter"><code>DACS_JURISDICTION</code></em>
The jurisdiction that received the service request, if available.
</p></li><li class="listitem"><p><em class="parameter"><code>FORMAT</code></em>,
the value of this parameter will be either HTML or XML, as
determined by the value of the parameter of the same name passed
to <span class="command"><strong>dacs_authenticate</strong></span> or the default (HTML if
<em class="parameter"><code>FORMAT</code></em> was not specified).
</p></li></ol></div><p>
The values of these parameters are URL encoded.
</p></li><li class="listitem"><p><code class="literal"><span class="property">AUTH_ERROR_HANDLER</span>
"<em class="replaceable"><code>AUTH-error-code</code></em> [file] <em class="replaceable"><code>full-pathname</code></em>"</code>
</p><p>This form causes the contents of
the file named by <em class="replaceable"><code>full-pathname</code></em> to
be returned without regard to the presence of a
<em class="parameter"><code>FORMAT</code></em> argument.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note19"></a>Note</h3><p>The file must include any header lines it requires, such as a
<span class="property">Content-Type</span> line, a header-terminating blank line,
and then the document content.
Note also that the "<code class="literal">full-pathname</code>" usage differs from
the "<code class="literal">local-URL</code>" usage of the
<span class="property">ACS_ERROR_HANDLER</span> directive, though both
elements begin with a slash character; the former specifies the absolute
pathname of a file, while the latter specifies a URL local to the receiving
web server.
</p></div></li><li class="listitem"><p><code class="literal"><span class="property">AUTH_ERROR_HANDLER</span>
"<em class="replaceable"><code>AUTH-error-code</code></em> [message] \"<em class="replaceable"><code>message</code></em>\""</code>
</p><p>This form causes the given message,
surrounded by escaped double quote
characters, to be returned as HTML (or XML
if <code class="literal">FORMAT=XML</code>).
</p></li></ol></div><p>The optional keywords are treated case-insensitively.
</p><p>The <em class="replaceable"><code>AUTH-error-code</code></em> is
either a defined authentication error code (listed
above) or the special symbol "<code class="literal">*</code>", which means the
directive applies to any
authentication error code for which there is no explicit directive.</p><p>This directive may appear multiple times,
although multiple directives for
the same <em class="replaceable"><code>AUTH-error-code</code></em> are not allowed.
Any invalid directive will
generally be treated as a fatal error. A directive with a syntactically
valid but undefined <em class="replaceable"><code>AUTH-error-code</code></em> is ignored,
however.
</p></dd><dt><span class="term"><a name="AUTH_FAIL"></a>
<span class="property">AUTH_FAIL</span> (Optional1)</span></dt><dd><p>If <span class="command"><strong>dacs_authenticate</strong></span>
fails to authenticates a user, the given
expression is evaluated just before the
<a class="ulink" href="#AUTH_ERROR_HANDLER" target="_top">AUTH_ERROR_HANDLER</a> directive,
if any, is processed.
This directive provides a hook for post-authentication actions to be
performed.
The namespaces in effect during authentication processing are
accessible to the expression.
The value of the expression is discarded and any errors are ignored.
Note that since authentication failed, only the user's purported identity
may be available
(<code class="varname"><a name="var_args_username"></a>${Args::USERNAME}</code>),
or if the user was previously authenticated successfully,
as
<code class="varname"><a name="var_env_remote_user"></a>${Env::REMOTE_USER}</code>.
</p></dd><dt><span class="term"><a name="AUTH_FAIL_DELAY_SECS"></a>
<span class="property">AUTH_FAIL_DELAY_SECS</span> (Optional1)</span></dt><dd><p>If assigned a positive integer value,
a particular user (ordinarily the one identified by
the <em class="parameter"><code>USERNAME</code></em> argument to
<span class="command"><strong>dacs_authenticate</strong></span>) will not be allowed
to reauthenticate following a failed attempt within this many seconds.
If assigned the value of zero seconds, this feature is disabled.
If this directive is absent or assigned an illegal value,
a compile-time value is used instead.
Authentication modules may indirectly impose their own delays
following unsuccessful authentication; this is system dependent and
not under the control of <span class="command"><strong>DACS</strong></span>.
</p></dd><dt><span class="term"><a name="AUTH_SINGLE_COOKIE"></a>
<span class="property">AUTH_SINGLE_COOKIE</span> (Optional1)</span></dt><dd><p>By default, each set of credentials that is returned
in an HTTP cookie is assigned a
<a class="ulink" href="dacs_authenticate.8.html#credentials" target="_top">cookie name</a>
that corresponds to the identity represented by the credentials.
If a user authenticates as two different identities through
<span class="command"><strong>dacs_authenticate</strong></span>, for example, he will be given
two cookies with different names.
Because in some situations multiple credentials can be problematic,
this directive provides a way to effectively limit a request to a single
set of credentials by using one cookie name for all credentials.
When an already-authenticated user authenticates again,
either at the same jurisdiction or any jurisdiction,
the user's browser will replace the previous cookie with the new one.
</p><p>This directive also controls cookie names associated with
credentials generated by
<a class="ulink" href="dacscookie.1.html" target="_top">dacscookie(1)</a>,
<a class="ulink" href="dacs_auth_agent.8.html" target="_top">dacs_auth_agent(8)</a>, and
<a class="ulink" href="dacs_auth_transfer.8.html" target="_top">dacs_auth_transfer(8)</a>.
Also see
<a class="ulink" href="#ACS_CREDENTIALS_LIMIT" target="_top">ACS_CREDENTIALS_LIMIT</a>.
</p><p>By setting <span class="property">AUTH_SINGLE_COOKIE</span> to
"<code class="literal">jurisdiction</code>" (case insensitive),
the username component of an authentication cookie issued by the
jurisdiction is suppressed.
This means that every authentication cookie it creates will have the
same name.
By setting it to "<code class="literal">federation</code>" (case insensitive),
the jurisdiction and username components of an authentication cookie
issued by the jurisdiction are suppressed.
This means that every authentication cookie that it creates will have the
same name, but also that any two jurisdictions that use this configuration
will create cookies with the same name.
Any other value results in the default behaviour,
which is to include both the jurisdiction name and the username
in the names of authentication cookies.
The directive has no effect on the name of the identity encapsulated
within an HTTP cookie.
</p><p>If an authentication cookie is received that was created by the
jurisdiction and has a cookie name with a component that it has been
configured to suppress, the cookie is ignored.
A cookie issued by a different jurisdiction with a suppressed cookie name
component is acceptable regardless of how this directive is configured
at this jurisdiction.
<span class="command"><strong>DACS</strong></span> will reject all credentials if a request includes
more than one cookie with the same cookie name.
</p><p>In typical use, each jurisdiction that performs authentication will
configure this directive identically.
To limit each user to associating a single identity with their request,
simply set <span class="property">AUTH_SINGLE_COOKIE</span> to
"<code class="literal">federation</code>" at each jurisdiction in the federation.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security4"></a>Security</h3><p>This directive indirectly limits the number of credentials that can be
associated with a single request.
It does not prevent the same individual from sending different requests,
from the same browser or different browsers, each associated with a different
identity.
Also, it does not limit the number of concurrent logins of the same
identity (such as by different individuals sharing the same account).
</p><p>Changing this directive's value may render existing
credentials invalid at this jurisdiction.
For example, after changing the directive it is possible for a user
to obtain two authentication cookies with different names for the same
identity.
<span class="command"><strong>DACS</strong></span> does not allow a request to include multiple
credentials for the same identity.
</p></div></dd><dt><span class="term"><a name="AUTH_SUCCESS"></a>
<span class="property">AUTH_SUCCESS</span> (Optional)</span></dt><dd><p>If <span class="command"><strong>dacs_authenticate</strong></span>
successfully authenticates a user, the given
expression is evaluated just before the
<a class="ulink" href="#AUTH_SUCCESS_HANDLER" target="_top">AUTH_SUCCESS_HANDLER</a> directive,
if any, is processed.
This directive provides a hook for post-authentication actions to be
performed, which can be user-specific.
The namespaces in effect during authentication processing are
accessible to the expression.
The value of the expression is discarded and any errors are ignored.
</p><p>Also see the
<a class="ulink" href="dacs.exprs.5.html#on_success" target="_top">on_success()</a> function.
</p><p>As an example, the following directive will run a web service
after every successful login:
</p><pre class="screen">
AUTH_SUCCESS 'https://internal.example.com/cgi-bin/userlogin?USERNAME=${Auth::IDENTITY}'
</pre><p>
</p></dd><dt><span class="term"><a name="AUTH_SUCCESS_HANDLER"></a>
<span class="property">AUTH_SUCCESS_HANDLER</span> (Optional1)</span></dt><dd><p>If <span class="command"><strong>dacs_authenticate</strong></span>
successfully authenticates a user, the resulting action
can be customized.
This provides a way for the <span class="command"><strong>DACS</strong></span>
administrator to redirect a user's browser after login.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note20"></a>Note</h3><p>This feature is enabled only if
<span class="command"><strong>dacs_authenticate</strong></span> is passed an
<em class="parameter"><code>ENABLE_AUTH_HANDLERS</code></em> parameter that has a value of
<code class="literal">1</code>.
</p></div><p>The <span class="command"><strong>dacs_authenticate</strong></span>
service recognizes a <em class="parameter"><code>FORMAT</code></em> argument that is used to
select between an XML-aware user agent
(<code class="literal">FORMAT=XML</code>) and an HTML capable user
agent (<em class="parameter"><code>FORMAT</code></em>
is not specified or is not XML).
In the case of an XML result,
<a class="ulink" href="../dtd-xsd/dacs_auth_reply.dtd" target="_top">dacs_auth_reply.dtd</a>
is used. The behaviour of this directive with
respect to <em class="parameter"><code>FORMAT</code></em>
is described below on a case-by-case basis.
</p><p>The following syntaxes are supported:
</p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p><code class="literal"><span class="property">AUTH_SUCCESS_HANDLER</span> "[url] <em class="replaceable"><code>URL</code></em>"</code>
</p><p>This form causes <span class="command"><strong>DACS</strong></span>
to redirect the client to <em class="replaceable"><code>URL</code></em>,
which may be a relative or absolute URL.
If the keyword <code class="literal">url</code> is absent,
<em class="replaceable"><code>URL</code></em>
must begin with the four characters <code class="literal">http</code>.
The <code class="literal">GET</code> method will be used.
The URL may contain a properly escaped query string; <span class="command"><strong>DACS</strong></span>
will append the following parameters, in the order given, to the URL:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>DACS_VERSION</code></em></span></dt><dd><p>The
version number of <span class="command"><strong>DACS</strong></span>
(e.g., "<code class="literal">1.4</code>").</p></dd><dt><span class="term"><em class="parameter"><code>DACS_FEDERATION</code></em></span></dt><dd><p>The
federation that received the service request, if available.</p></dd><dt><span class="term"><em class="parameter"><code>DACS_JURISDICTION</code></em></span></dt><dd><p>The
jurisdiction that received the service request, if available.</p></dd><dt><span class="term"><em class="parameter"><code>DACS_USERNAME</code></em></span></dt><dd><p>The
username associated with the new credentials.</p></dd><dt><span class="term"><em class="parameter"><code>FORMAT</code></em></span></dt><dd><p>The
value of this parameter will be either HTML or XML, as
determined by the value of the parameter of the same name passed
to <span class="command"><strong>dacs_authenticate</strong></span> or the default
(HTML if <em class="parameter"><code>FORMAT</code></em> was not specified).</p></dd></dl></div><p>The values of these parameters are URL encoded.
</p></li><li class="listitem"><p><code class="literal"><span class="property">AUTH_SUCCESS_HANDLER</span> "[file] <em class="replaceable"><code>full-pathname</code></em>"</code>
</p><p>This form causes the contents of the file
named by <em class="replaceable"><code>full-pathname</code></em> to
be returned without regard to the presence of
a <em class="parameter"><code>FORMAT</code></em> argument.
The file must include any header lines it requires, such as a
<span class="property">Content-Type</span>
line, a header-terminating blank line, and then the document content.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note21"></a>Note</h3><p>The "<code class="literal">full-pathname</code>" usage differs from
the "<code class="literal">local-URL</code>" usage of the
<span class="property">ACS_ERROR_HANDLER</span> directive, though both
elements begin with a slash character; the former specifies the absolute
pathname of a file, while the latter specifies a URL local to the receiving
web server.
To specify a relative URL, use the <code class="literal">url</code> keyword.
</p></div></li><li class="listitem"><p><code class="literal"><span class="property">AUTH_SUCCESS_HANDLER</span> "[message] \"<em class="replaceable"><code>message</code></em>\""</code>
</p><p>This form causes the given message,
surrounded by escaped double quote
characters, to be returned as HTML (or XML if
<code class="literal">FORMAT=XML</code>).
</p></li><li class="listitem"><p><code class="literal"><span class="property">AUTH_SUCCESS_HANDLER</span> "credentials"</code>
</p><p>This form causes the user's credentials to
be displayed, either as an HTML or XML
(if <code class="literal">FORMAT=XML</code>) document. This is the default behaviour.
</p></li></ol></div><p>The optional keywords are treated case-insensitively.
</p></dd><dt><span class="term"><a name="AUTH_TRANSFER_EXPORT"></a>
<span class="property">AUTH_TRANSFER_EXPORT</span> (Optional)</span></dt><dd><p>Each use of this directive identifies a target federation
and the corresponding URL of a program to invoke the
<code class="literal">TOKEN</code> operation phase of the protocol in that federation.
The federation identifier is simply a label (case-sensitive) that
must be a syntactically valid federation name.
Whitespace separates the federation name from the URL.
Please refer to
<a class="ulink" href="dacs_auth_transfer.8.html" target="_top">dacs_auth_transfer(8)</a>
for details.
</p></dd><dt><span class="term"><a name="AUTH_TRANSFER_TOKEN_LIFETIME_SECS"></a>
<span class="property">AUTH_TRANSFER_TOKEN_LIFETIME_SECS</span> (Optional1)</span></dt><dd><p>This is the lifetime, in seconds, of a token
produced by the <code class="literal">TOKEN</code> operation of
<a class="ulink" href="dacs_auth_transfer.8.html" target="_top">dacs_auth_transfer(8)</a>
and consumed by its <code class="literal">IMPORT</code> operation.
That is, it is the time a user (or middleware) has to submit the token
before it becomes invalid.
It should be on the order of a few seconds.
</p></dd><dt><span class="term"><a name="COMPAT_MODE"></a>
<span class="property">COMPAT_MODE</span> (Optional1)</span></dt><dd><p>This indicates that, to the extent possible,
credentials issued by a different release of <span class="command"><strong>DACS</strong></span>
should be accepted.
At present, the only supported values are <code class="literal">off</code>
(the default, which disables this mode) and <code class="literal">1.2</code>.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security5"></a>Important</h3><p>This directive is
<span class="emphasis"><em>not</em></span> intended to provide complete
interoperability among <span class="command"><strong>DACS</strong></span> releases and in fact
it does not in certain situations.
Old releases of <span class="command"><strong>DACS</strong></span> may contain security-related bugs,
or may rely on third-party software that contains security-related bugs.
<span class="command"><strong>DACS</strong></span> installations are urged to upgrade rather than
to depend on the limited backward compatibility supplied by this directive.
<span class="emphasis"><em>There is no guarantee that any particular level of backward
compatibility will be carried forward in subsequent releases of</em></span>
<span class="command"><strong>DACS</strong></span>.
</p></div><p>
</p></dd><dt><span class="term"><a name="COOKIE_HTTPONLY"></a>
<span class="property">COOKIE_HTTPONLY</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>", the <code class="literal">HttpOnly</code>
attribute will be included with cookies produced by <span class="command"><strong>DACS</strong></span>.
This attribute is a Microsoft extension that is used to
"<a class="ulink" href="http://msdn.microsoft.com/en-us/library/ms533046%28VS.85%29.aspx" target="_top">mitigate
the risk of information disclosure with a cross-site scripting (XSS)
attack</a>".
This attribute is not recognized by all browsers but these browsers
should ignore it.
The default is "<code class="literal">no</code>".
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security6"></a>Security</h3><p>
Methods of defeating this attribute
<a class="ulink" href="http://www.webappsec.org/lists/websecurity/archive/2006-05/msg00025.html" target="_top">
are known</a>,
so administrators may need to take additional precautions against
XSS attacks.
</p></div></dd><dt><span class="term"><a name="COOKIE_NAME_TERMINATORS"></a>
<span class="property">COOKIE_NAME_TERMINATORS</span> (Optional1)</span></dt><dd><p>By default, <span class="command"><strong>DACS</strong></span> creates HTTP cookies
with names having
<a class="ulink" href="dacs_authenticate.8.html#cookie-name-syntax" target="_top">a particular syntax</a>,
using colon characters to separate components of the cookie's name:
application name ("DACS"), federation name, jurisdiction name, and username.
The strings that are used by default to terminate the first three components
of the cookie name can be changed using this directive.
If the directive's value is:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>a single character, each occurrence of a colon in the default
terminators is replaced by the character;
</p></li><li class="listitem"><p>a string that does not contain a comma,
each occurrence of a colon in the default terminators is replaced
by the string; or
</p></li><li class="listitem"><p>a string that contains four commas,
each terminator in the default format is replaced by the corresponding
component in <span class="property">COOKIE_NAME_TERMINATORS</span>.
</p></li></ul></div><p>
Any other directive value is rejected.
It is not possible to escape a comma in the directive value.
No terminator may be the null string.
This directive is honoured in all contexts where <span class="command"><strong>DACS</strong></span>
produces or parses an HTTP cookie name,
such as by
<a class="ulink" href="dacscookie.1.html" target="_top">dacscookie(1)</a>.
See <a class="ulink" href="dacs_authenticate.8.html#COOKIE_SYNTAX" target="_top">COOKIE_SYNTAX</a>
for additional information.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security14"></a>Important</h3><p>No other validity checks are performed,
so it is possible to configure a cookie name syntax that is non-conformant,
unacceptable to <span class="command"><strong>DACS</strong></span>,
or unacceptable to some clients.
Changing the cookie name format will cause previously issued cookies
to not be recognized by <span class="command"><strong>DACS</strong></span> until the format is
switched back.
Since the value of the directive can be determined at run-time,
however, considerable flexibility is possible.
Jurisdictions will not recognize each other's HTTP cookies if they produce
cookies with differently formatted names.
Changing the cookie name format does not affect the similar syntax
used to specify jurisdictions, users, and so on.
</p></div><p>
Consider this directive:
</p><pre class="programlisting">
COOKIE_NAME_TERMINATORS "~"
</pre><p>
This will result in cookie names that look like:
</p><pre class="programlisting">
DACS~<em class="replaceable"><code>federation-name</code></em>~~[<em class="replaceable"><code>jurisdiction-name</code></em>]~[<em class="replaceable"><code>username</code></em>][~<em class="replaceable"><code>special</code></em>]
</pre><p>
Here is another example:
</p><pre class="programlisting">
COOKIE_NAME_TERMINATORS "~,::,~,:"
</pre><p>
This will result in cookie names that look like:
</p><pre class="programlisting">
DACS~<em class="replaceable"><code>federation-name</code></em>::[<em class="replaceable"><code>jurisdiction-name</code></em>]~[<em class="replaceable"><code>username</code></em>][:<em class="replaceable"><code>special</code></em>]
</pre><p>
</p></dd><dt><span class="term"><a name="COOKIE_NO_DOMAIN"></a>
<span class="property">COOKIE_NO_DOMAIN</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>", no <code class="literal">domain</code>
attribute will appear when <span class="command"><strong>DACS</strong></span> returns a cookie,
such as after authenticating successfully from a browser.
The browser will take the default action, which is to associate the
cookie with the domain name or IP address of the request that returned
the cookie.
This will obviously limit <span class="command"><strong>DACS's</strong></span> single sign-on
feature since the cookie (credentials) will only be sent with requests
made to that domain name or IP address.
</p><p>This directive is sometimes useful when <span class="command"><strong>DACS</strong></span> is
deployed in an environment where fully qualified domain names are not used.
In this case, <span class="property">FEDERATION_DOMAIN</span> must still be
configured, although it will not be used in conjunction with the
<code class="literal">domain</code> of cookies.
</p><p>The default is "<code class="literal">no</code>".
</p></dd><dt><span class="term"><a name="COOKIE_PATH"></a>
<span class="property">COOKIE_PATH</span> (Optional1)</span></dt><dd><p>This allows the path component of a
<code class="literal">Set-Cookie</code>
(and <code class="literal">Set-Cookie2</code>) HTTP
response header to be specified for the jurisdiction.
These headers are sent
to a user agent after successful authentication or signout.
Refer to the
<a class="ulink" href="http://web.archive.org/web/20070805052634/http://wp.netscape.com/newsref/std/cookie_spec.html" target="_top">Netscape
HTTP Cookies Specification</a>,
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2965.txt" target="_top">RFC 2965</a>,
and
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc6265.txt" target="_top">RFC 6265</a>
for details.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security7"></a>Security</h3><p>
The default value is "<span class="path">/</span>",
which means that the cookie will be sent by a user agent
along with <span class="emphasis"><em>every</em></span> request sent to the jurisdiction's host.
The value should be set to the most specific URL path under which
all <span class="command"><strong>DACS</strong></span>-wrapped services appear so that
<span class="command"><strong>DACS</strong></span> credentials
will only be sent with requests to those URLs.
It is critical to do this if your
server runs arbitrary user CGI programs because a malicious user might be
able to cause a <span class="command"><strong>DACS</strong></span>-authenticated user to visit a service
that is not
<span class="command"><strong>DACS</strong></span>-wrapped and capture cookies that represent
<span class="command"><strong>DACS</strong></span> identities.
For example, if a jurisdiction segregated its <span class="command"><strong>DACS</strong></span>-wrapped
static content under
<span class="path">/dacs/content</span>
and its <span class="command"><strong>DACS</strong></span>-wrapped
CGI programs under
<span class="path">/dacs/cgi-bin</span>, then
<span class="property">COOKIE_PATH</span> should have the value
"<code class="literal">/dacs</code>".
</p></div></dd><dt><span class="term"><a name="CSS_PATH"></a>
<span class="property">CSS_PATH</span> (Optional1)</span></dt><dd><p>This path is used as the value of the <code class="literal">href</code>
attribute of the HTML <code class="literal">link</code> element used to specify the
root location of style files used by HTML-producing <span class="command"><strong>DACS</strong></span>
web services and utilities.
The mapping between this path and a local directory, if any, depends
on <span class="command"><strong>Apache's</strong></span> configuration; for example, if its value is
"<code class="literal">/css</code>", the location of the corresponding directory
will depend on the location of the server's document root and
any applicable <span class="property">Alias</span> directive.
</p><p>If this directive is not used, a compile-time default of
"<code class="literal">/css</code>" is used, which assumes that an
<span class="command"><strong>Apache</strong></span> directive like this one is used:
</p><pre class="screen">
Alias /css "/usr/local/dacs/www/css/"
</pre><p>
Please refer to
<a class="ulink" href="dacs.install.7.html" target="_top">dacs.install(7)</a> for
additional information about use of the <span class="property">Alias</span> directive.
</p></dd><dt><span class="term"><a name="DTD_BASE_URL"></a>
<span class="property">DTD_BASE_URL</span> (Optional1)</span></dt><dd><p>When <span class="command"><strong>DACS</strong></span> services are asked to send
an XML response (<code class="literal">FORMAT=XML</code>) and
<span class="property">DTD_BASE_URL</span> is configured, services will emit a
<code class="literal">DOCTYPE</code> with the keyword <code class="literal">SYSTEM</code>
followed by a value derived from
<span class="property">DTD_BASE_URL</span>; e.g.,
</p><pre class="programlisting">
<!DOCTYPE foo SYSTEM "http://example.com/dacs/dtd-xsd/foo.dtd">
</pre><p>
If <span class="property">DTD_BASE_URL</span>
is not configured, an internal DTD will be emitted.
Also see the description of the
<a class="ulink" href="dacs.services.8.html#FORMAT" target="_top"><em class="parameter"><code>FORMAT</code></em>
web service argument</a>.
</p></dd><dt><span class="term"><a name="EVAL"></a>
<span class="property">EVAL</span> (Optional)</span></dt><dd><p>The <span class="property">EVAL</span> directive is special in
that it may appear in any clause and because it is
<span class="emphasis"><em>always evaluated when it is first seen</em></span>
during processing of
<code class="filename">site.conf</code>, the <code class="literal">Default</code> section of
<code class="filename">dacs.conf</code>, or the applicable
<code class="literal">Jurisdiction</code> section of
<code class="filename">dacs.conf</code>
(i.e., before any section merging occurs).
The purpose of the directive is purely for its side effect, such as
initializing a configuration variable
(see <a class="ulink" href="#advanced" target="_top">Advanced Techniques</a>).
Because these directives are scanned early during configuration processing,
their right-hand sides cannot reference directives as configuration
variables because those directives have not yet been evaluated
(so they cannot reference
<code class="varname"><a name="var_conf_federation_domain"></a>${Conf::FEDERATION_DOMAIN}</code>,
for example).
Example:
</p><pre class="programlisting">
EVAL ${Conf::a_special_path} = "/my/path"
</pre><p>
</p></dd><dt><span class="term"><a name="FEDERATION_DOMAIN"></a>
<span class="property">FEDERATION_DOMAIN</span> (Required1)</span></dt><dd><p>The suffix of the domain name
(<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc1035.txt" target="_top">RFC 1035</a> 2.3.1)
that is common to all jurisdictions in the federation.
Note that the domain name associated with a jurisdiction is not
explicitly configured
(but see <code class="literal">dacs_url</code> in
<a class="ulink" href="dacs.groups.5.html#group_syntax" target="_top">dacs.groups(5)</a>),
and that this is a one-to-many association
(see
<a class="ulink" href="dacs.conf.5.html#jurisdiction_section_overview" target="_top">dacs.conf(5)</a>).
Example:
<span class="domainname">example.com</span>
</p></dd><dt><span class="term"><a name="FEDERATION_NAME"></a>
<span class="property">FEDERATION_NAME</span> (Required1)</span></dt><dd><p>The name for the federation of jurisdictions.
The syntax is the same as for
<a class="ulink" href="#JURISDICTION_NAME" target="_top">JURISDICTION_NAME</a>:
an alphabetic followed by zero or more alphanumeric
characters, '<code class="literal">-</code>', or '<code class="literal">_</code>'.
By convention, this is in all-caps, however.
Please see
<a class="ulink" href="dacs.1.html#naming" target="_top">dacs(1)</a> for additional information.
Example: <code class="literal">FEDROOT</code>
</p></dd><dt><span class="term"><a name="HTTP_AUTH"></a>
<span class="property">HTTP_AUTH</span> (Stack)</span></dt><dd><p>This directive is used to perform user authentication
<span class="emphasis"><em>at access control time</em></span> rather than in a separate
sign-on step.
This mode of authentication is triggered through
<span class="command"><strong>DACS's</strong></span> internal implementation of HTTP Basic
or Digest authentication
(see <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2617.txt" target="_top">RFC 2617</a>).
If prompting is enabled, the user will be asked for his username and
password by the user agent's usual prompting method.
If prompting is disabled, the user agent must know how to send an
<code class="literal">Authorization</code> request header without first receiving
a <code class="literal">WWW-Authenticate</code> response header.
The username and password obtained from the user can be directed to any
suitable <span class="command"><strong>DACS</strong></span> authentication method for validation.
By default,
the resulting identity is associated with the
<a class="ulink" href="dacs.1.html#current_jurisdiction" target="_top">current jurisdiction</a>.
</p><p>Other than by placing the resource or resources specified by
this directive under the control of <span class="command"><strong>DACS</strong></span>,
no additional <span class="command"><strong>Apache</strong></span> configuration needs to be done to
use this feature.
</p><p>Please refer to the section on
<a class="ulink" href="dacs_acs.8.html#http_authentication" target="_top">HTTP Authentication</a>
for additional information about this feature and how it is used.
Also refer to the <a class="ulink" href="#HTTP_AUTH_ENABLE" target="_top">HTTP_AUTH_ENABLE</a>
directive.
</p><p>Two different mechanisms are available:
<span class="emphasis"><em>pre-authorization</em></span> testing and
<span class="emphasis"><em>post-authorization</em></span> testing.
The <span class="property">HTTP_AUTH_ENABLE</span> directive is used to enable
one or both mechanisms.
</p><p>The <span class="emphasis"><em>pre-authorization</em></span> testing mechanism is used if:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>a request is received that does not include valid credentials;
</p></li><li class="listitem"><p>the feature is enabled by <span class="property">HTTP_AUTH_ENABLE</span>
(i.e., it is set to "<code class="literal">pre_acs_only</code>"
or "<code class="literal">both</code>")
and not disabled by
<a class="ulink" href="#ACS_AUTHENTICATED_ONLY" target="_top">ACS_AUTHENTICATED_ONLY</a>;
</p></li><li class="listitem"><p>no
<a class="ulink" href="#ACS_PRE_AUTH" target="_top">ACS_PRE_AUTH</a> directive is successful;
</p></li><li class="listitem"><p>the applicable directive includes the <code class="option">-pre</code>
flag (<a class="ulink" href="#http_auth_syn2" target="_top">see below</a>); and
</p></li><li class="listitem"><p>either the request includes an
<code class="literal">Authorization</code> request header or the return of an HTTP
<code class="literal">WWW-Authenticate</code> response header is enabled.
</p></li></ol></div><p>
This mechanism can be useful with simple user agents that understand
Basic authentication but cannot handle redirection or sometimes even the
<code class="literal">WWW-Authenticate</code> response header.
It may also be appropriate in situations where a user agent cannot or
will not handle HTTP cookies.
If <span class="command"><strong>dacs_acs</strong></span> is allowed to respond with a
<code class="literal">WWW-Authenticate</code> response header,
the configuration variable
<code class="varname"><a name="var_http_auth_401"></a>${Conf::http_auth_401}</code>
must be set to "<code class="literal">yes</code>".
</p><p>The <span class="emphasis"><em>post-authorization</em></span> testing mechanism is used if:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>a request is denied because the user was not authenticated;
</p></li><li class="listitem"><p>the feature is enabled by <span class="property">HTTP_AUTH_ENABLE</span>
(i.e., it is set to "<code class="literal">post_acs_only</code>"
or "<code class="literal">both</code>")
and not disabled by <span class="property">ACS_AUTHENTICATED_ONLY</span>;
</p></li><li class="listitem"><p>the applicable directive does not include a
<code class="option">-pre</code> flag (see below).
</p></li></ol></div><p>
</p><p>One important difference between the two mechanisms is that while the
post-authorization mechanism works by redirecting the user to
<a class="ulink" href="dacs_authenticate.8.html" target="_top">dacs_authenticate(8)</a>
after authorization checking denies a request,
the pre-authorization mechanism does not involve any redirection and
<span class="command"><strong>dacs_authenticate</strong></span> is not used.
Instead, <span class="command"><strong>dacs_acs</strong></span> performs authentication internally
(by calling <span class="command"><strong>dacsauth</strong></span> as a function) and
<span class="emphasis"><em>credentials are not returned to the client</em></span>;
credentials are created that (normally) exist only for the duration of the
authorization check,
which means that no <span class="command"><strong>DACS</strong></span> session state exists outside
of <span class="command"><strong>dacs_acs</strong></span> and therefore some <span class="command"><strong>DACS</strong></span>
web services will either be unavailable or not operate in the same way
they would if credentials were provided by the client.
Pre-authorization may also be less efficient than returning credentials
because authentication will be performed each and every time the client
makes a request that triggers it.
Note that only authentication modules that implement
the <code class="literal">password</code> or <code class="literal">expr</code>
<a class="ulink" href="dacs_authenticate.8.html#STYLE" target="_top">authentication styles</a>
can be used by this mechanism,
and only if no redirection of the client is necessary.
Because web browsers only prompt for a username and password,
if an <em class="parameter"><code>AUXILIARY</code></em> argument is also required it must
be entered with either the username or password (i.e., combined in some
way, perhaps separated by punctuation) and then parsed into an
<em class="parameter"><code>AUXILIARY</code></em> argument using a run-time configuration
directive.
With pre-authorization, roles can be assigned to the temporary credentials
(refer to the description of the <code class="option">-r</code> flag and the
<em class="replaceable"><code>role-module-spec</code></em> in
<a class="ulink" href="dacsauth.1.html" target="_top">dacsauth(1)</a> for details).
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security8"></a>Security</h3><p>Like <span class="command"><strong>dacsauth</strong></span> and
<span class="command"><strong>dacs_authenticate</strong></span>, if <span class="command"><strong>dacs_acs</strong></span>
uses a built-in module to perform authentication,
it must run setuid or setgid
(<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=chmod&apropos=0&esektion=2&emanpath=FreeBSD+10.3-RELEASE&format=html" target="_top">chmod(2)</a>).
to obtain sufficient privileges to access the required files;
this is true for Unix password authentication, for example.
Programs should run at the lowest level of authorization that is necessary,
however, and it is generally preferable to only run authentication modules
at a higher authorization level.
</p></div><p>
</p><p>The value of the <span class="property">HTTP_AUTH</span> directive follows
any one of the following three forms:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><pre class="screen">
<em class="replaceable"><code>auth_scheme</code></em> <em class="replaceable"><code>auth_realm</code></em> <em class="replaceable"><code>url_pattern</code></em><code class="literal">+</code>
</pre></li><li class="listitem"><pre class="screen">
<em class="replaceable"><code>auth_scheme</code></em> <em class="replaceable"><code>auth_realm</code></em> <em class="replaceable"><code>url_pattern</code></em><code class="literal">+</code> -pre [[-param] <em class="replaceable"><code>param-string</code></em>]
{-m <em class="replaceable"><code>auth-module-spec</code></em> [<em class="replaceable"><code>auth-flag</code></em>]*}+ {-r <em class="replaceable"><code>roles-module-spec</code></em>}*
</pre></li><li class="listitem"><pre class="screen">
except <em class="replaceable"><code>url_pattern</code></em><code class="literal">+</code>
</pre></li></ol></div><p>
</p><p><a name="http_auth_syn1"></a>The first syntactical form is for the
post-authentication mechanism:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><em class="replaceable"><code>auth_scheme</code></em>
is the (case-insensitive) authentication scheme to use
(e.g., <code class="literal">Basic</code>);
</p></li><li class="listitem"><p><em class="replaceable"><code>auth_realm</code></em> is the
(case-sensitive) realm-value string associated with the resource
(see <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2617.txt" target="_top">RFC 2617</a>);
</p></li><li class="listitem"><p><em class="replaceable"><code>url_pattern</code></em><code class="literal">+</code>
is a list of one or more URI path components that are matched against the
request for which access was denied to an unauthenticated user.
Each of these components is like the <em class="replaceable"><code>url_pattern</code></em>
attribute used in
<a class="ulink" href="dacs.acls.5.html#elements" target="_top">access control rules</a>
in that it can either specify an exact match or, by ending in
"<span class="path">/*</span>", a wildcard match;
no query argument component is allowed.
Each <em class="replaceable"><code>url_pattern</code></em> begins with a
<code class="literal">/</code> character.
</p></li></ul></div><p>
</p><p><a name="http_auth_syn2"></a>The second syntactical form is for the
pre-authentication mechanism.
Its first three components are like those for the first form,
and must appear in the order specified above.
The following components are then added, and may follow the three initial
components in any order:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="option">-pre</code> selects the pre-authorization testing
mechanism;
the default is to use post-authorization testing.
Because each <em class="replaceable"><code>url_pattern</code></em> begins with a
<code class="literal">/</code> character, the <code class="option">-pre</code> flag implicitly
ends the <em class="replaceable"><code>url_pattern</code></em> list.
</p></li><li class="listitem"><p><em class="replaceable"><code>param-string</code></em> is an optional
string consisting of authentication parameters as per RFC 2617
(note: HTTP Basic authentication does not permit any optional parameters).
For clarity, or if <em class="replaceable"><code>param-string</code></em> might be confused
with another syntactic element, it can be preceded by a
<code class="option">-param</code> flag.
In the absence of the <code class="option">-param</code> flag,
any non-flag argument is assumed to be the
<em class="replaceable"><code>param-string</code></em>.
Only one <em class="replaceable"><code>param-string</code></em> is allowed.
</p></li><li class="listitem"><p><code class="option">-m</code> <em class="replaceable"><code>auth-module-spec</code></em>
specifies an authentication module using the command-line syntax of
<a class="ulink" href="dacsauth.1.html" target="_top">dacsauth(1)</a>.
This argument must occur at least once.
Following the <em class="replaceable"><code>auth-module-spec</code></em> can be zero or
more <em class="replaceable"><code>auth-flag</code></em> arguments to apply to the
module's authentication context.
The
<code class="option">-D<em class="replaceable"><code>directive</code></em>=<em class="replaceable"><code>value</code></em></code> flag,
<code class="option">-fj <em class="replaceable"><code>jurname</code></em></code> flag, and the
<code class="option">-fn <em class="replaceable"><code>fedname</code></em></code> flag
are recognized and have the same semantics as when used by
<a class="ulink" href="dacsauth.1.html" target="_top">dacsauth(1)</a>.
</p></li><li class="listitem"><p><code class="option">-r</code>
<em class="replaceable"><code>roles-module_spec</code></em>
specifies a roles module.
This argument may occur zero or more times.
</p></li></ul></div><p>
</p><p><a name="http_auth_syn3"></a>In the third syntactical form,
the <code class="literal">except</code> keyword identifies portions of
the URL space that should <span class="emphasis"><em>not</em></span> trigger HTTP authentication.
</p><p>The <span class="property">HTTP_AUTH</span> directives "stack",
like the <a class="ulink" href="#ACS_ERROR_HANDLER" target="_top">ACS_ERROR_HANDLER</a> directive.
<span class="command"><strong>DACS</strong></span> will search for the first exact
<em class="replaceable"><code>url_pattern</code></em> that matches or will
select the closest wildcard <em class="replaceable"><code>url_pattern</code></em>.
Two or more directives with the same <em class="replaceable"><code>url_pattern</code></em>
should not be configured.
</p><p>The first of the two directives in the following example
may trigger Basic authentication for the realm called "Info Realm" when
either
<span class="path">/cgi-bin/dacs/dacs_prenv</span>
or
<span class="path">/cgi-bin/dacs/dacs_version</span>
(relative to the
<a class="ulink" href="dacs.1.html#current_jurisdiction" target="_top">current jurisdiction</a>)
is requested.
The second directive may trigger Basic authentication
for the realm called "CGI Realm" for any other resource subordinate to
<span class="path">/cgi-bin/dacs</span>.
The first directive will override the second because an exact match
overrides a wildcard match.
</p><pre class="programlisting">
HTTP_AUTH "basic \"Info Realm\" /cgi-bin/dacs/dacs_prenv /cgi-bin/dacs/dacs_version"
HTTP_AUTH "basic \"CGI Realm\" /cgi-bin/dacs/*"
</pre><p>
</p><p>In the next example,
the two directives associate the Basic authentication scheme
with everything under <span class="path">/cgi-bin/dacs/</span>,
except for <span class="path">/cgi-bin/dacs/dacs_prenv</span>
(because the second directive is an exact match, which overrides the first
directive):
</p><pre class="programlisting">
HTTP_AUTH "basic \"CGI Realm\" /cgi-bin/dacs/*"
HTTP_AUTH "except /cgi-bin/dacs/dacs_prenv"
</pre><p>
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>An administrator can take advantage of
<span class="command"><strong>DACS's</strong></span> active configuration processing to decide
at run-time which <em class="replaceable"><code>auth_scheme</code></em>,
<em class="replaceable"><code>auth_realm</code></em>,
or password file to use, for instance, perhaps depending on the
request's arguments.
</p></div><p>As an example of pre-authorization testing authentication,
consider the following configuration directives:
</p><pre class="programlisting">
HTTP_AUTH_ENABLE "pre_acs_only"
EVAL ${Conf::http_auth_401} = "no"
HTTP_AUTH "basic \"dacs_prenv Realm\" /cgi-bin/dacs/dacs_prenv -m unix passwd suff"
</pre><p>
The first directive above enables this feature.
The second directive disables responding with a
<code class="literal">WWW-Authenticate</code> header;
changing its value to "<code class="literal">yes</code>" enables the response.
The third directive associates the <span class="command"><strong>DACS</strong></span>
<a class="ulink" href="dacs_prenv.8.html" target="_top">dacs_prenv(8)</a> service with
the built-in Basic authentication feature at pre-authorization testing time.
Given this configuration, if a client requests <span class="command"><strong>dacs_prenv</strong></span>
but does not include credentials:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>if no <code class="literal">Authorization</code> header was sent
and <code class="varname">${Conf::http_auth_401}</code> is "<code class="literal">no</code>",
then execution will proceed as if the feature were disabled
(i.e., the user will be unauthenticated)
</p></li><li class="listitem"><p>if no <code class="literal">Authorization</code> header was sent and
<code class="varname">${Conf::http_auth_401}</code> is "<code class="literal">yes</code>",
then <span class="command"><strong>DACS</strong></span> will respond with a
<code class="literal">WWW-Authenticate</code> response header and
<code class="constant">401</code> status code
</p></li><li class="listitem"><p>if an <code class="literal">Authorization</code> header was sent,
the username and password will be validated using the built-in Unix
authentication module:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>if authentication succeeds, temporary credentials will
be created and used for the request, but will not be returned to the client
</p></li><li class="listitem"><p>if authentication fails, access will be denied
</p></li></ul></div><p>
</p></li></ul></div><p>
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>You can create an <code class="literal">Authorization</code> header by
constructing a string consisting of an account name, a colon, and the
account's password.
MIME encode the resulting string - you can use
<a class="ulink" href="dacsexpr.1.html" target="_top">dacsexpr(1)</a> and the
<a class="ulink" href="dacs.exprs.5.html#encode" target="_top">encode()</a> function:
</p><pre class="screen">
% dacsexpr
> encode(mime, "guest:apassword")
"Z3Vlc3Q6YXBhc3N3b3Jk"
</pre><p>
The header for the example above would look like:
</p><pre class="screen">
Authorization: Basic Z3Vlc3Q6YXBhc3N3b3Jk
</pre><p>
And using <a class="ulink" href="dacshttp.1.html" target="_top">dacshttp(1)</a>,
you could use the flag:
</p><pre class="screen">
-header Authorization "Basic Z3Vlc3Q6YXBhc3N3b3Jk"
</pre><p>
</p></div><p>The example that follows shows how
<a class="ulink" href="dacs_authenticate.8.html#local_ldap_authenticate" target="_top">LDAP authentication</a>
using the <code class="literal">direct</code> method might be configured.
In an appropriate place in <code class="filename">dacs.conf</code>, we might insert
these directives:
</p><pre class="programlisting">
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \"LDAP Login Using Your Common Name\" /basic/* -pre \
-m https://example.example.com/cgi-bin/dacs/local_ldap_authenticate \
password sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct"
</pre><p>
In the file <code class="filename">/usr/local/dacs/ldap/ldap_auth_options_direct</code>
(which must be readable at run-time by
<a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a>), we might put:
</p><pre class="programlisting">
LDAP_BIND_METHOD=direct
LDAP_USERNAME_URL*="ldap://windex.example.com/CN=" . encode(url,${Args::USERNAME}) . ",CN=Users,DC=example,DC=com"
LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
</pre><p>
Note the use of the <span class="property">LDAP_USERNAME_EXPR*</span> directive.
Because authentication against the directory uses a
<code class="literal">Common Name</code> attribute in the example, and a
<code class="literal">Common Name</code> may not be a valid <span class="command"><strong>DACS</strong></span>
username, it must be replaced by (or mapped to) an acceptable
<span class="command"><strong>DACS</strong></span> username.
The first time a user attempts to access a resource that matches the
URL pattern <code class="literal">/basic/*</code>,
he will prompted by his web browser for a username
(in this case, a <code class="literal">Common Name</code> must be provided) and password.
The directory on
<span class="domainname">windex.example.com</span>
will be used by the <span class="command"><strong>local_ldap_authenticate</strong></span> module
to validate the information provided by the user.
</p><p>To also obtain the user's roles from the directory,
the <code class="literal">set_roles</code> style modifier and an
<span class="property">LDAP_ROLES_SELECTOR*</span> directive can be added to the
configuration:
</p><pre class="programlisting">
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \"LDAP Login Using Your Common Name\" /basic/* -pre \
-m https://example.example.com/cgi-bin/dacs/local_ldap_authenticate \
password,set_roles sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct"
</pre><p>
And to <code class="filename">/usr/local/dacs/ldap/ldap_auth_options_direct</code>:
</p><pre class="programlisting">
LDAP_BIND_METHOD=direct
LDAP_USERNAME_URL*="ldap://windex.example.com/CN=" . encode(url,${Args::USERNAME}) . ",CN=Users,DC=example,DC=com"
LDAP_ROLES_SELECTOR*="${LDAP::attrname}" eq "memberOf" ? strtr(ldap(rdn_attrvalu
e, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
</pre><p>
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>Since the pre-authorization mechanism does not return
<span class="command"><strong>DACS</strong></span> credentials to the user's web browser,
a subsequent invocation of
<a class="ulink" href="dacs_current_credentials.8.html" target="_top">dacs_current_credentials(8)</a>
will not display information that resulted from the authentication procedure.
If the URL that triggers pre-authorization is for a script or other program
that is executable by <span class="command"><strong>Apache</strong></span> with access permitted by
<span class="command"><strong>DACS</strong></span>, however, the program can display its environment,
which will include <code class="envar">DACS_USERNAME</code>, <code class="envar">DACS_ROLES</code>,
and so on.
For example,
<a class="ulink" href="dacs_prenv.8.html" target="_top">dacs_prenv(8)</a> can be used for this,
as can this simple PHP script (<span class="command"><strong>phpinfo.php</strong></span>):
</p><pre class="programlisting">
<html><head></head><body>
<p>
<?php
phpinfo();
?>
</p>
</body>
</html>
</pre><p>
</p></div><p>To authenticate against a Unix account and assign the user's group
membership as roles, this configuration might be used:
</p><pre class="programlisting">
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \"Login Using Your Unix Account\" /basic/* -pre \
-m https://example.example.com/cgi-bin/dacs/local_unix_authenticate \
password sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct \
-r https://example.example.com/cgi-bin/dacs/local_unix_roles"
</pre><p>
Note that <span class="command"><strong>local_unix_authenticate</strong></span> must run with
sufficient privileges to validate the username/password pair.
</p></dd><dt><span class="term"><a name="HTTP_AUTH_ENABLE"></a>
<span class="property">HTTP_AUTH_ENABLE</span> (Optional1)</span></dt><dd><p>This directive's value must be one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>"<code class="literal">post_acs_only</code>",
if only post-authorization testing
<a class="ulink" href="dacs_acs.8.html#http_authentication" target="_top">HTTP Authentication</a>
may be used,
</p></li><li class="listitem"><p>"<code class="literal">pre_acs_only</code>",
if only pre-authorization testing HTTP authentication may be used, or
</p></li><li class="listitem"><p>"<code class="literal">yes</code>" or "<code class="literal">both</code>"
if either mechanism may be used.
</p></li></ul></div><p>
Refer to <a class="ulink" href="#HTTP_AUTH" target="_top">HTTP_AUTH</a> for additional details.
</p></dd><dt><span class="term"><a name="HTTP_PROG"></a>
<span class="property">HTTP_PROG</span> (Required1)</span></dt><dd><p>The full pathname of the executable
<a class="ulink" href="dacshttp.1.html" target="_top">dacshttp(1)</a>
program, a utility distributed with <span class="command"><strong>DACS</strong></span>.
This program is used by <span class="command"><strong>DACS</strong></span> components to invoke
local services, optionally using SSL/TLS.
</p></dd><dt><span class="term"><a name="INFOCARD_AUDIENCE"></a>
<span class="property">INFOCARD_AUDIENCE</span> (Optional)</span></dt><dd><p>This directive must be configured for <span class="command"><strong>DACS</strong></span>
to function as a Relying Party.
When <span class="command"><strong>DACS</strong></span> acts as a Relying Party,
each of these directives is applied to the value of an
<code class="literal">Audience</code> element (a URI) in a secure token's
<code class="literal">AudienceRestrictionCondition</code> element
until a successful match is found.
Several matching functions are available using the following syntax:
</p><pre class="programlisting">
<em class="replaceable"><code>function</code></em> [<span class="emphasis"><em>space</em></span>+ <em class="replaceable"><code>arg-to-match-against-Audience</code></em>]
</pre><p>
<em class="replaceable"><code>function</code></em> is case insensitive.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">uri</code> <em class="replaceable"><code>match-URI</code></em></span></dt><dd><p>The <em class="replaceable"><code>match-URI</code></em> is
compared with the entire <code class="literal">Audience</code> URI for an exact URI match.
URI matching syntax is used, meaning that only the scheme and hostname
components are case insensitive.
</p><pre class="screen">
INFOCARD_AUDIENCE "uri http://DACS.DSS.CA/infocard-demo"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">any</code></span></dt><dd><p>Any <code class="literal">Audience</code> is acceptable.
</p><pre class="screen">
INFOCARD_AUDIENCE "any"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">regex</code> <em class="replaceable"><code>match-regex</code></em><br></span><span class="term"><code class="literal">regex/</code><em class="replaceable"><code>flags</code></em> <em class="replaceable"><code>match-regex</code></em></span></dt><dd><p>In the first form,
the regular expression <em class="replaceable"><code>match-regex</code></em> is matched
(unanchored) against the <code class="literal">Audience</code> URI.
In the second form, one or more flags can precede the regular expression:
'<code class="literal">i</code>' specifies case-insensitive matching and
'<code class="literal">e</code>' specifies "extended" regular expressions rather than
the default "basic" regular expressions.
IEEE Std 1003.2 ("POSIX.2")
regular expressions are supported
(<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&esektion=3&emanpath=FreeBSD+10.3-RELEASE&format=html" target="_top">regex(3)</a>).
</p><pre class="screen">
INFOCARD_AUDIENCE "regex/i ^https://dacs.dss.ca:8443"
</pre><p>
The following directives are equivalent:
</p><pre class="screen">
INFOCARD_AUDIENCE "regex .*"
INFOCARD_AUDIENCE "any"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">host</code> <em class="replaceable"><code>match-hostname</code></em></span></dt><dd><p>The <em class="replaceable"><code>match-hostname</code></em>, which may be a
domain name or an IP address, is matched case-insensitively against
the host name in the <code class="literal">Audience</code> URI.
</p><pre class="screen">
INFOCARD_AUDIENCE "host dacs.dss.ca"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">prefix</code> <em class="replaceable"><code>match-URI</code></em></span></dt><dd><p>The <em class="replaceable"><code>match-URI</code></em>
is matched against the <code class="literal">Audience</code> URI to test if the
former is a prefix of the latter.
The case-sensitivity rules for URI components is respected
(e.g., the scheme and host name components are treated case-insensitively,
but the path components are not).
</p><pre class="screen">
INFOCARD_AUDIENCE "prefix https://dacs.dss.ca/infocards"
</pre><p>
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_AUDIENCE_RESTRICTION"></a>
<span class="property">INFOCARD_AUDIENCE_RESTRICTION</span> (Optional)</span></dt><dd><p>Used by <a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>,
this optional directive specifies the value of an
<code class="literal">Audience</code> element in an
<code class="literal">AudienceRestrictionCondition</code>.
</p></dd><dt><span class="term"><a name="INFOCARD_CARD_DATETIME_EXPIRES"></a>
<span class="property">INFOCARD_CARD_DATETIME_EXPIRES</span> (Optional1)</span></dt><dd><p>This optional directive specifies the date and time of
expiration for a managed InfoCard created by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>.
The XML Schema <span class="type">dateTime</span> format must be used
(see <a class="ulink" href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#dateTime" target="_top">XML Schema Part 2: Datatypes Second Edition</a>); e.g.,
</p><pre class="screen">
INFOCARD_CARD_DATETIME_EXPIRES "2010-06-15T09:46:31-08:00"
</pre><p>
Also see
<a class="ulink" href="#INFOCARD_CARD_LIFETIME_SECS" target="_top">INFOCARD_CARD_LIFETIME_SECS</a>.
</p></dd><dt><span class="term"><a name="INFOCARD_CARD_DEFS_URL"></a>
<span class="property">INFOCARD_CARD_DEFS_URL</span> (Optional1)</span></dt><dd><p>This optional directive is used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
to specify a web service that defines the claims supported by a
new managed InfoCard.
If it is not defined, the default claim <code class="literal">dacs_identity</code>
is used.
To prevent abuse, arbitrary
compile-time limits are imposed on the number of claims (20)
and the lengths of various claim components:
name (32 bytes),
value (64 bytes),
URI prefix (128 bytes),
label (20 bytes), and
description (40 bytes).
(These limits should be run-time configurable.)
The distribution's <span class="directory">infocard</span> directory
includes an example program, <span class="command"><strong>demo_card_defs.php</strong></span>,
which documents the program's arguments and output syntax.
</p></dd><dt><span class="term"><a name="INFOCARD_CARD_FILL_URL"></a>
<span class="property">INFOCARD_CARD_FILL_URL</span> (Optional1)</span></dt><dd><p>This optional directive is used by
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>
to specify a web service that retrieves the values of claims
requested by a Relying Party.
If it is not defined, only the value of the default claim
<code class="literal">dacs_identity</code> is available.
Access to this web service must be appropriately restricted and secured,
although it does not need to be <span class="command"><strong>DACS</strong></span>-wrapped.
It is passed special <span class="command"><strong>DACS</strong></span> credentials (as an HTTP cookie).
The distribution's <span class="directory">infocard</span> directory
includes an example program, <span class="command"><strong>demo_fill_claims.php</strong></span>,
which documents the program's arguments and output syntax.
</p></dd><dt><span class="term"><a name="INFOCARD_CARD_IMAGE_BASE_URL"></a>
<span class="property">INFOCARD_CARD_IMAGE_BASE_URL</span> (Required1-C)</span></dt><dd><p>This directive is required by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>.
It is the initial part of a <span class="command"><strong>DACS</strong></span>
<a class="ulink" href="#VFS" target="_top">VFS URI</a> from which image files
for managed InfoCards can be retrieved.
The general idea is that the particular image associated with a card
depends on the STS authentication credential that is used by the card.
For example, the configuration variable
<code class="varname"><a name="var_infocard_card_image_passwd"></a>infocard_card_image_passwd</code>,
if set, specifies the filename (relative to
<span class="property">INFOCARD_CARD_IMAGE_BASE_URL</span>) of an image
associated with InfoCards that use the username/password type of authentication
between its owner and the STS;
if unspecified, a compile-time default
(<code class="filename">dacs_username_password_credential.png</code>) is used.
Similarly, the variables
<code class="varname"><a name="var_infocard_card_image_cert"></a>infocard_card_image_cert</code>
(default value: <code class="filename">dacs_x509certificate_credential.png</code>) and
<code class="varname"><a name="var_infocard_card_image_card"></a>infocard_card_image_card</code>
(default value: <code class="filename">dacs_selfissued_credential.png</code>)
specify filenames for images
associated with the X.509 V3 certificate credential type
and the self-issued InfoCard credential type, respectively.
The value of <span class="property">INFOCARD_CARD_IMAGE_BASE_URL</span> is typically
the absolute pathname of a directory containing the image files or the initial
part of a URL to which a final path component will be appended.
Also see the
<a class="ulink" href="dacs_managed_infocard.8.html#CARD_IMAGE_URL" target="_top">CARD_IMAGE_URL</a>
argument to <span class="command"><strong>dacs_managed_infocard</strong></span>.
</p><p>An image should be in the range of 60 pixels wide by 45 pixels high
and 200 pixels wide by 150 pixels high.
Only certain image formats are allowed by the specification;
the image format is deduced from the filename extension (case insensitively):
"<span class="extension">.png</span>",
"<span class="extension">.gif</span>",
"<span class="extension">.tiff</span>"
(or "<span class="extension">.tif</span>"),
"<span class="extension">.bmp</span>", and
"<span class="extension">.jpeg</span>"
(or "<span class="extension">.jpg</span>").
If the format cannot be deduced, <acronym class="acronym">PNG</acronym> is assumed.
</p></dd><dt><span class="term"><a name="INFOCARD_CARD_LIFETIME_SECS"></a>
<span class="property">INFOCARD_CARD_LIFETIME_SECS</span> (Optional1)</span></dt><dd><p>If <span class="property">INFOCARD_CARD_DATETIME_EXPIRES</span>
is not defined, the expiration date and time of a managed InfoCard created by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
can be specified relative to the current time as this many seconds.
If neither this directive nor
<span class="property">INFOCARD_CARD_DATETIME_EXPIRES</span> is defined,
a compile-time default lifetime is used (currently, 365 days).
Also see
<a class="ulink" href="#INFOCARD_CARD_DATETIME_EXPIRES" target="_top">INFOCARD_CARD_DATETIME_EXPIRES</a>.
</p></dd><dt><span class="term"><a name="INFOCARD_CARD_OUTPUTDIR"></a>
<span class="property">INFOCARD_CARD_OUTPUTDIR</span> (Optional1)</span></dt><dd><p>If a managed InfoCard generated by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
is stored in a file, it is written to this directory.
The name of the file is of the form
<em class="replaceable"><code>username</code></em>_<em class="replaceable"><code>random</code></em><code class="literal">.crd</code>.
See <a class="ulink" href="#INFOCARD_CARDID_BASE_URL" target="_top">INFOCARD_CARDID_BASE_URL</a>.
</p></dd><dt><span class="term"><a name="INFOCARD_CARD_VERSION"></a>
<span class="property">INFOCARD_CARD_VERSION</span> (Optional1)</span></dt><dd><p>This directive is used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
to provide a value for the <code class="literal">CardVersion</code> element in
a managed InfoCard.
The default is "<code class="literal">1</code>".
</p></dd><dt><span class="term"><a name="INFOCARD_CARDID_BASE_URL"></a>
<span class="property">INFOCARD_CARDID_BASE_URL</span> (Required1-C)</span></dt><dd><p>This directive is required by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>.
It is used as the base URL for the <code class="literal">CardId</code> of a new
managed InfoCard.
If this URL is set so that it points into the directory
specified by
<a class="ulink" href="#INFOCARD_CARD_OUTPUTDIR" target="_top">INFOCARD_CARD_OUTPUTDIR</a>,
then the resulting <code class="literal">CardId</code> URLs can be used to
fetch the card by its owner, assuming appropriate access control rules
are also configured.
Also see <a class="ulink" href="#INFOCARD_CARDID_SUFFIX" target="_top">INFOCARD_CARDID_SUFFIX</a>.
</p></dd><dt><span class="term"><a name="INFOCARD_CARDID_SUFFIX"></a>
<span class="property">INFOCARD_CARDID_SUFFIX</span> (Optional1)</span></dt><dd><p>This optional directive is used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
and specifies a string to be appended as a final path element to
the value of
<a class="ulink" href="#INFOCARD_CARDID_BASE_URL" target="_top">INFOCARD_CARDID_BASE_URL</a>
to form a new card's <code class="literal">CardId</code>.
If the value of <span class="property">INFOCARD_CARDID_SUFFIX</span> is:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">identity</code></span></dt><dd><p>The specified or implied identity assigned to the card
is interpolated; this is the default.
</p></dd><dt><span class="term"><code class="literal">username</code></span></dt><dd><p>The specified or implied username assigned to the card is
interpolated.
</p></dd><dt><span class="term"><code class="literal">random</code></span></dt><dd><p>A safely-encoded 20-byte random string is interpolated.
</p></dd><dt><span class="term"><code class="literal">default</code></span></dt><dd><p>The default is used ("<code class="literal">identity</code>").
</p></dd></dl></div><p>
If the value of <span class="property">INFOCARD_CARDID_SUFFIX</span> does not
match (case-insensitively) any of these strings, it is interpolated verbatim.
Regardless of how it was derived, the result string must be a syntactically
valid URI path segment
(<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2396.txt" target="_top">RFC 2396</a>).
</p></dd><dt><span class="term"><a name="INFOCARD_DIGEST"></a>
<span class="property">INFOCARD_DIGEST</span> (Optional1)</span></dt><dd><p>The name of the hash algorithm to use in account files
for self-issued InfoCard-based authentication
(see <a class="ulink" href="dacs_infocard.8.html" target="_top">dacs_infocard(8)</a>).
The syntax is the same as for the
<a class="ulink" href="#PASSWORD_DIGEST" target="_top">PASSWORD_DIGEST</a> directive.
The default is "<code class="literal">SHA256</code>".
</p></dd><dt><span class="term"><a name="INFOCARD_IP_PRIVACY_URL"></a>
<span class="property">INFOCARD_IP_PRIVACY_URL</span> (Required1-C)</span></dt><dd><p>This directive is required by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a> and
specifies the URL of the Identity Provider's <code class="literal">PrivacyNotice</code>.
A default notice is configured.
</p></dd><dt><span class="term"><a name="INFOCARD_IP_PRIVACY_VERSION"></a>
<span class="property">INFOCARD_IP_PRIVACY_VERSION</span> (Optional1)</span></dt><dd><p>This optional directive is used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a> and
specifies an integer version number (greater than zero) of the document
returned by the
<a class="ulink" href="#INFOCARD_IP_PRIVACY_URL" target="_top">INFOCARD_IP_PRIVACY_URL</a>.
If it is set to the empty string, however, no version number will be
specified for the <code class="literal">PrivacyNotice</code>.
The default is "<code class="literal">1</code>".
</p></dd><dt><span class="term"><a name="INFOCARD_ISSUER_INFO_ENTRY"></a>
<span class="property">INFOCARD_ISSUER_INFO_ENTRY</span> (Optional)</span></dt><dd><p>This optional directive, which may be repeated, is
used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
to specify arbitrary descriptive information to be included in
managed InfoCards.
This information may be displayed by an Identity Selector.
The value of the directive is a string of the form
"<em class="replaceable"><code>EntryName</code></em><code class="literal">:</code><em class="replaceable"><code>EntryValue</code></em>".
</p></dd><dt><span class="term"><a name="INFOCARD_MEX_URL"></a>
<span class="property">INFOCARD_MEX_URL</span> (Required1-C)</span></dt><dd><p>This directive,
used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>,
specifies the URL of the
WS-MetadataExchange responder for managed InfoCards.
Also see <a class="ulink" href="dacs_mex.8.html" target="_top">dacs_mex(8)</a>.
</p></dd><dt><span class="term"><a name="INFOCARD_REQUIRE_APPLIES_TO"></a>
<span class="property">INFOCARD_REQUIRE_APPLIES_TO</span> (Optional1)</span></dt><dd><p>Used optionally by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>,
this directive controls a managed InfoCard's <code class="literal">RequireAppliesTo</code>
element, which by default is omitted.
This element is used to control whether the card's Identity Provider
(e.g., <a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>)
will be informed as to the identity of the Relying Party via the
<code class="literal">wsp:AppliesTo</code> element
(when it is informed, it is called an <span class="emphasis"><em>auditing card</em></span>,
which is used in <span class="emphasis"><em>auditing mode</em></span>).
Following the Identity Selector Interoperability Profile,
this directive may have any of the following values:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">no</code></span></dt><dd><p>The <code class="literal">RequireAppliesTo</code> element is omitted
(called a <span class="emphasis"><em>non-auditing card</em></span>).
</p></dd><dt><span class="term"><code class="literal">yes</code></span></dt><dd><p><code class="literal">RequireAppliesTo</code> is emitted,
but with its optional attribute omitted
(an <span class="emphasis"><em>auditing card</em></span>).
</p></dd><dt><span class="term"><code class="literal">true</code></span></dt><dd><p><code class="literal">RequireAppliesTo</code> is emitted
with the attribute <code class="literal">Optional="true"</code>
(called an <span class="emphasis"><em>auditing-optional card</em></span>).
</p></dd><dt><span class="term"><code class="literal">false</code></span></dt><dd><p><code class="literal">RequireAppliesTo</code> is emitted
with the attribute <code class="literal">Optional="false"</code>
(an <span class="emphasis"><em>auditing card</em></span>).
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_STRONG_RP_IDENTITY"></a>
<span class="property">INFOCARD_STRONG_RP_IDENTITY</span> (Optional1)</span></dt><dd><p>Used optionally by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>,
if the value of this directive is "<code class="literal">yes</code>"
<code class="literal">RequireStrongRecipientIdentity</code> is present in new
managed InfoCards, which indicates that a Relying Party
must use a cryptographically protected identity;
i.e., an X.509 server certificate.
</p></dd><dt><span class="term"><a name="INFOCARD_STS_AUTH_TYPE"></a>
<span class="property">INFOCARD_STS_AUTH_TYPE</span> (Required1-C)</span></dt><dd><p>This directive, required by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>,
specifies (case-insensitively) the authentication credential type,
which identifies an Identity Selector user to an IP/STS
(see <a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>).
The value of this directive is consulted when a new managed InfoCard
is created; the type may be changed without affecting the authentication
credential type assigned to InfoCards created before the change.
Recognized values are:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">password</code><br></span><span class="term"><code class="literal">passwd</code></span></dt><dd><p>This is the username/password credential type.
See
<a class="ulink" href="#INFOCARD_STS_PASSWORD_METHOD" target="_top">INFOCARD_STS_PASSWORD_METHOD</a>.
</p></dd><dt><span class="term"><code class="literal">cert</code></span></dt><dd><p>This is the X.509 V3 certificate credential type.
An SSL client certificate must be used with the request to
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
for a managed InfoCard,
and the same certificate must be used when the managed InfoCard is
submitted to a Relying Party.
A self-signed certificate may be used.
</p></dd><dt><span class="term"><code class="literal">card</code></span></dt><dd><p>This is the self-issued credential type.
A self-issued InfoCard must be submitted with the request to
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
for a managed InfoCard,
and the same self-issued InfoCard must be available to the user's
Identity Selector when the managed InfoCard is submitted to a Relying Party.
This self-issued InfoCard does not need to be separately registered
using <a class="ulink" href="dacs_infocard.8.html" target="_top">dacs_infocard(8)</a>.
</p></dd><dt><span class="term"><code class="literal">kerberos</code></span></dt><dd><p>This is the Kerberos V5 credential type.
This authentication credential type is currently unsupported.
</p></dd></dl></div><p>
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>Although the specification allows an ordered list of
STS endpoints to appear, at present only a single endpoint may be configured.
</p></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_STS_CACERTFILE"></a>
<span class="property">INFOCARD_STS_CACERTFILE</span> (Required1-C)</span></dt><dd><p>This directive, which is required by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>,
specifies the filename of the certificate authority's
PEM-encoded X.509 certificate
for <a class="ulink" href="#INFOCARD_STS_CERTFILE" target="_top">INFOCARD_STS_CERTFILE</a>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>File permissions and ownership must be set appropriately to allow
run-time access.</p></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_STS_CERTFILE"></a>
<span class="property">INFOCARD_STS_CERTFILE</span> (Required1-C)</span></dt><dd><p>This directive, which is required by
<a class="ulink" href="dacsinfocard.1.html" target="_top">dacsinfocard(1)</a>,
<a class="ulink" href="dacs_infocard.8.html" target="_top">dacs_infocard(8)</a>, and
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>,
specifies the filename of the PEM-encoded X.509 certificate for the
Secure Token Service provided by
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>File permissions and ownership must be set appropriately to allow
run-time access.
If a self-signed certificate is being used,
the appropriate root certificate must be installed on the system that is running
the Identity Selector.
</p></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_STS_KEYFILE"></a>
<span class="property">INFOCARD_STS_KEYFILE</span> (Required1-C)</span></dt><dd><p>This directive, which is required by
<a class="ulink" href="dacsinfocard.1.html" target="_top">dacsinfocard(1)</a>,
<a class="ulink" href="dacs_authenticate.8.html#local_infocard_authenticate" target="_top">local_infocard_authenticate</a>,
<a class="ulink" href="dacs_infocard.8.html" target="_top">dacs_infocard(8)</a>,
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>, and
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>,
specifies the filename of the key for the X.509 certificate
specified by <span class="property">INFOCARD_STS_CERTFILE</span>.
If this file is password protected,
<a class="ulink" href="#INFOCARD_STS_KEYFILE_PASSWORD" target="_top">INFOCARD_STS_KEYFILE_PASSWORD</a>
must be configured.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>File permissions and ownership must be set appropriately to allow
run-time access.</p></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_STS_KEYFILE_PASSWORD"></a>
<span class="property">INFOCARD_STS_KEYFILE_PASSWORD</span> (Required1-C)</span></dt><dd><p>If
<a class="ulink" href="#INFOCARD_STS_KEYFILE" target="_top">INFOCARD_STS_KEYFILE</a>
is encrypted, this directive is required to specify the password.
</p></dd><dt><span class="term"><a name="INFOCARD_STS_PASSWORD_METHOD"></a>
<span class="property">INFOCARD_STS_PASSWORD_METHOD</span> (Required1-C)</span></dt><dd><p>If the username/password credential type is needed
by a managed InfoCard,
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a> requires this directive
to specify how the username and password are to be validated:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">empty</code></span></dt><dd><p>The password is no password at all (i.e., the empty string).
If a password <span class="emphasis"><em>is</em></span> given, authentication will fail.
</p></dd><dt><span class="term"><code class="literal">ignore</code></span></dt><dd><p>Any password string, including no password at all
(i.e., the empty string), is acceptable.
</p></dd><dt><span class="term"><code class="literal">sts</code></span></dt><dd><p>The given password string must exactly match
the authentication-time value of the configuration variable
<code class="varname"><a name="var_infocard_sts_password"></a>infocard_sts_password</code>.
</p></dd><dt><span class="term"><code class="literal">account:</code><em class="replaceable"><code>id</code></em></span></dt><dd><p>The given username and password must be valid relative
to the specified <span class="command"><strong>DACS</strong></span> authentication module identified
by the <code class="literal">Auth</code> clause label <em class="replaceable"><code>id</code></em>,
which must be enabled and configured as per
<a class="ulink" href="dacs_authenticate.8.html" target="_top">dacs_authenticate(8)</a>.
(Note: <span class="emphasis"><em>This form is currently unsupported</em></span>.)
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_STS_RP_ENDPOINT"></a>
<span class="property">INFOCARD_STS_RP_ENDPOINT</span> (Optional)</span></dt><dd><p>This directive causes
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a> to issue
security tokens only to selected identified Relying Parties;
if the identity of a Relying Party, as provided by the
<code class="literal">Address</code> endpoint appearing
in the token request's <code class="literal">AppliesTo</code> element
(apparently the URL of the Relying Party's web page) does not match any instance
of this directive, a token will not be returned.
A token will be returned if this directive is not used or if the Relying Party
is not identified.
Not all Relying Parties are identified;
see
<a class="ulink" href="#INFOCARD_REQUIRE_APPLIES_TO" target="_top">INFOCARD_REQUIRE_APPLIES_TO</a>.
The syntax for this directive is identical to that of
<a class="ulink" href="#INFOCARD_AUDIENCE" target="_top">INFOCARD_AUDIENCE</a>.
Although the Relying Party's server certificate can be provided with the
identification material in the token request,
it is not currently accessible to this directive.
</p></dd><dt><span class="term"><a name="INFOCARD_STS_URL"></a>
<span class="property">INFOCARD_STS_URL</span> (Required1-C)</span></dt><dd><p>This directive,
used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>,
<a class="ulink" href="dacs_mex.8.html" target="_top">dacs_mex(8)</a>, and
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>,
specifies the URL of the
Secure Token Service for managed InfoCards.
</p></dd><dt><span class="term"><a name="INFOCARD_TOKEN_DRIFT_SECS"></a>
<span class="property">INFOCARD_TOKEN_DRIFT_SECS</span> (Optional1)</span></dt><dd><p>A security token (produced by
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>, for instance)
bears a validity condition;
a relying party may reject a token if its current system date/time lies
outside of the time window prescribed by the token.
Because the clock at the IP/STS (which issued the token) and the clock
at the relying party may not be closely synchronized -
the relying party's clock may be faster or slower than the IP/STS's clock -
a relying party may be willing to permit a certain amount of "clock drift"
before it rejects a token.
This directive specifies the maximum number of seconds that
the IP/STS's clock may be too fast or too slow.
If the directive's value is zero, or if the directive is not configured,
a compile time default value is used (currently, 300 seconds).
If the directive's value is "<code class="literal">disable</code>",
the validity test is suppressed.
</p></dd><dt><span class="term"><a name="INFOCARD_TOKEN_ISSUER"></a>
<span class="property">INFOCARD_TOKEN_ISSUER</span> (Required1-C)</span></dt><dd><p>This directive,
used by
<a class="ulink" href="dacs_managed_infocard.8.html" target="_top">dacs_managed_infocard(8)</a>
and
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>,
specifies the <code class="literal">Issuer</code> of a managed InfoCard as a URI.
The value "<code class="literal">self</code>" can be used to represent
the special URI identifying a self-issued InfoCard.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>If your Identity Selector does not let you choose a managed
InfoCard when you think that it ought to
(i.e., the value of this directive in effect when the managed InfoCard was
created matches the web page's <code class="literal">issuer</code> parameter),
it seems that the <span class="property">INFOCARD_TOKEN_ISSUER</span>
is ignored by an Identity Selector in preference to the name
in the Identity Provider's SSL certificate.
It has been noted that if a Relying Party uses a
<a class="ulink" href="http://wiki.cacert.org/wiki/WildcardCertificates" target="_top">wildcard certificate</a>,
an Identity Selector may have trouble matching the
<em class="parameter"><code>issuer</code></em> parameter in an HTML
<code class="literal">OBJECT</code> request with an InfoCard;
it may be necessary for the Relying Party to specify the value of the
<em class="parameter"><code>issuer</code></em> parameter as the empty string.
</p></div><p>
</p></dd><dt><span class="term"><a name="INFOCARD_TOKEN_LIFETIME_SECS"></a>
<span class="property">INFOCARD_TOKEN_LIFETIME_SECS</span> (Optional1)</span></dt><dd><p>This optional directive
specifies the lifetime, in seconds, of a secure token created by
<a class="ulink" href="dacs_sts.8.html" target="_top">dacs_sts(8)</a>.
If not provided, a compile-time value is used.
To reduce the window of vulnerability where a token might be captured
and used by an attacker, this period should be relatively short
(on the order of a few seconds).
Note that a Relying Party is free to account for
inadequately synchronized clocks when deciding whether it should
accept a token, so this lifetime is effectively a recommendation for the
recipient of the token.
If the clocks at the Identity Selector and token issuer are not
sufficiently synchronized, the Identity Selector will reject a token
if the token's validity window is outside of its clock's current value.
</p></dd><dt><span class="term"><a name="INFOCARD_TOKEN_MAX_LENGTH"></a>
<span class="property">INFOCARD_TOKEN_MAX_LENGTH</span> (Optional1)</span></dt><dd><p>A relying party can use this directive to specify the
maximum size (in bytes) of a security token that it will accept.
If this directive is not configured or is zero,
a compile time default value is used (currently, 16384 bytes).
</p></dd><dt><span class="term"><a name="INFOCARD_USERNAME_SELECTOR"></a>
<span class="property">INFOCARD_USERNAME_SELECTOR</span> (Optional1)</span></dt><dd><p>This directive determines how the
<span class="command"><strong>DACS</strong></span> username is selected for a self-issued InfoCard
during registration by
<a class="ulink" href="dacs_infocard.8.html" target="_top">dacs_infocard(8)</a>.
The resulting identity is relative to the
<a class="ulink" href="dacs.1.html#current_jurisdiction" target="_top">current jurisdiction</a>;
that is, if the InfoCard is used to sign on at a jurisdiction
where it was registered, the jurisdiction will issue credentials for
the username that was registered with the InfoCard.
The following directive values are recognized:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">credentials</code></span></dt><dd><p>The username is obtained from the identity in effect
at registration time;
there may only be one such set of credentials and they must have been
issued by the jurisdiction at which registration is occurring.
This is the default behaviour if the directive is not given.
</p></dd><dt><span class="term"><code class="literal">email</code></span></dt><dd><p>The username is obtained from the email address field of the
InfoCard; the email address must be a syntactically valid username
(see <a class="ulink" href="dacs.1.html#naming" target="_top">dacs(1)</a>).
</p></dd><dt><span class="term"><code class="literal">webpage</code></span></dt><dd><p>The username is derived from the web page URL field of the
InfoCard; this is not currently implemented.
(see <a class="ulink" href="dacs.1.html#naming" target="_top">dacs(1)</a>).
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><a name="JURISDICTION_NAME"></a>
<span class="property">JURISDICTION_NAME</span> (Required1)</span></dt><dd><p>The name of the jurisdiction.
The syntax is the same as for
<a class="ulink" href="#FEDERATION_NAME" target="_top">FEDERATION_NAME</a>:
an alphabetic followed by zero or more alphanumerics,
'<code class="literal">-</code>' (hyphens),
or '<code class="literal">_</code>' (underscores).
Note that periods are not permitted.
By convention, this name is in all-caps,
Please see
<a class="ulink" href="dacs.1.html#naming" target="_top">dacs(1)</a> for additional information.
Example: <code class="literal">METALOGIC</code>
</p></dd><dt><span class="term"><a name="LOGINGEN_FILE"></a>
<span class="property">LOGINGEN_FILE</span> (Optional1)</span></dt><dd><p>Reserved for future use.
(Used with the <span class="command"><strong>DACS</strong></span> <span class="command"><strong>logingen</strong></span> utility,
this directive gives the full pathname of the template file.)
</p></dd><dt><span class="term"><a name="LOGINGEN_PROG"></a>
<span class="property">LOGINGEN_PROG</span> (Optional1)</span></dt><dd><p>Reserved for future use.
(Used with the <span class="command"><strong>DACS</strong></span> <span class="command"><strong>logingen</strong></span> utility,
this directive specifies a program
which will read <span class="property">LOGINGEN_FILE</span> on its
<span class="symbol">stdin</span>
and write the filtered output to <span class="symbol">stdout</span>.)
</p></dd><dt><span class="term"><a name="LOG_FILE"></a>
<span class="property">LOG_FILE</span> (Optional1)</span></dt><dd><p><span class="command"><strong>DACS</strong></span> uses the
<span class="property">LOG_FILE</span> directive to identify the primary
file to which it should write log information.
<span class="command"><strong>DACS</strong></span> performs directory name
interpolation on the pathname string using a syntax and method similar to
<span class="command"><strong>Apache's</strong></span>
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mod_vhost_alias.html" target="_top"><code class="function">mod_vhost_alias</code></a>
module
(see
<a class="ulink" href="#interpolation" target="_top">String Interpolation</a>).
</p><p>The result after interpolation
must either be the absolute pathname of
a file to write log information to, or the word "<code class="literal">syslog</code>".
In the latter case,
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=syslog&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">syslog(3)</a>
is used, with an
<em class="parameter"><code>ident</code></em> argument of "<code class="literal">dacs</code>" and
a facility of "<code class="literal">user</code>".
Each <span class="command"><strong>DACS</strong></span> logging level is mapped to the
corresponding <code class="function">syslog</code> level, with the
<code class="literal">trace</code> level mapped to <code class="function">syslog's</code>
<code class="literal">debug</code> level.
</p><p>While <span class="command"><strong>DACS</strong></span> is starting and before it reads
and processes its configuration files, this directive is not
yet available to it; until <span class="command"><strong>DACS</strong></span> knows what
<span class="property">LOG_FILE</span> is, or should
<span class="property">LOG_FILE</span> not be writable, the value of
<span class="property">LOG_FILE</span> is obtained from the value of
<span class="symbol">DACS_LOG</span>.
A compile-time specified value,
<span class="symbol">DACS_LOG</span> can be specified when <span class="command"><strong>DACS</strong></span>
is built
(the default is equivalent to
<span class="path">${Conf::DACS_HOME}/logs/error_log</span>).
If <span class="symbol">DACS_LOG</span> is unusable, <span class="symbol">stderr</span> is used.
</p></dd><dt><span class="term"><a name="LOG_FILTER"></a>
<span class="property">LOG_FILTER</span> (Stack)</span></dt><dd><p>This directive configures a fine-grained
way of specifying which messages will be written
compared to the
<a class="ulink" href="#LOG_LEVEL" target="_top">LOG_LEVEL</a> directive.
The directive, which may be repeated, selects the types of events that
<span class="command"><strong>DACS</strong></span> <span class="emphasis"><em>should</em></span> log;
unselected events are not recorded in a log file.
It also provides a way for different kinds of messages to be logged to
different files.
</p><p>Because this directive is in the
<a class="ulink" href="#directive_categories" target="_top"><code class="literal">Stack</code>
category</a>, "later" directives supercede earlier ones.
When a directive is found that allows a message to be logged, no additional
directives are examined for the message.
If this directive is not given, the default filtering is done based on
the <span class="property">LOG_LEVEL</span> and
<span class="property">LOG_SENSITIVE</span> directives.
</p><p>The syntax is one of:
</p><pre class="programlisting">
LOG_FILTER "<em class="replaceable"><code>type</code></em> <em class="replaceable"><code>flag</code></em>[,<em class="replaceable"><code>flag</code></em>]* <em class="replaceable"><code>level</code></em> <em class="replaceable"><code>name</code></em> [[<code class="literal">+</code>|<code class="literal">-</code>]<em class="replaceable"><code>file</code></em>]"
LOG_FILTER "<code class="literal">any</code> <em class="replaceable"><code>flag</code></em>[,<em class="replaceable"><code>flag</code></em>]* <em class="replaceable"><code>level</code></em> [[<code class="literal">+</code>|<code class="literal">-</code>]<em class="replaceable"><code>file</code></em>]"
</pre><p>
</p><p>The <em class="replaceable"><code>type</code></em>, which is one of the keywords
<code class="literal">program</code>, <code class="literal">module</code>,
<code class="literal">filename</code>, or <code class="literal">function</code>
(case insensitive),
specifies the type of the event source to which this filter applies;
i.e., it indicates what <em class="replaceable"><code>name</code></em> is to be matched
against.
If <em class="replaceable"><code>type</code></em> is <code class="literal">filename</code>,
for instance, it means that for this
filter to be applicable to a particular log message, the
<em class="replaceable"><code>name</code></em> must match the filename from which the
log message is generated.
</p><p>A list of comma-separated, case-insensitive modifier flags
specifies how matching of <em class="replaceable"><code>type</code></em> is done against
<em class="replaceable"><code>name</code></em>.
A <em class="replaceable"><code>flag</code></em> can have the value <code class="literal">exact</code>,
<code class="literal">regex</code>, <code class="literal">icase</code>,
<code class="literal">sensitive</code>, <code class="literal">user</code>,
<code class="literal">audit</code>, or <code class="literal">normal</code>.
</p><p>The <em class="replaceable"><code>name</code></em> is matched against
<em class="replaceable"><code>type</code></em> case sensitively,
unless the <code class="literal">icase</code> flag is present.
Matching is performed using
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">regex(3)</a>
regular expression matching if the <code class="literal">regex</code> flag is present,
or using a string comparison if the <code class="literal">exact</code>
flag is present (these two flags are mutually exclusive).
</p><p>A message can have no attributes associated with it,
or any combination of the attributes
<code class="literal">sensitive</code>, <code class="literal">user</code>, and
<code class="literal">audit</code>.
Messages with the <code class="literal">sensitive</code> attribute
might include potentially private information, such as a password.
Messages with the <code class="literal">audit</code> attribute include relatively
high-level events, such as successful and unsuccessful authentication results,
signouts, and access control decisions.
The <code class="literal">user</code> attribute is associated with messages produced by
the <a class="ulink" href="dacs.exprs.5.html#print" target="_top">print()</a> and
<a class="ulink" href="dacs.exprs.5.html#printf" target="_top">printf()</a> functions.
</p><p>Modifier flags are used to select (or deselect) messages to be logged.
By default, only <code class="literal">normal</code> messages are logged; these
are messages without any attributes.
The
<a class="ulink" href="#LOG_SENSITIVE" target="_top">LOG_SENSITIVE</a> directive can change the
default to enable <code class="literal">sensitive</code> messages.
</p><p>If the <code class="literal">audit</code> flag is given,
a message is logged only if it has that attribute.
Messages with the <code class="literal">sensitive</code> attribute
are not logged unless the <code class="literal">sensitive</code> flag is given,
and messages with the <code class="literal">user</code> attribute are not
logged unless the <code class="literal">user</code> flag is given.
</p><p>Assuming the <em class="replaceable"><code>type</code></em>
and <em class="replaceable"><code>level</code></em> do not deselect the message,
here are some example cases:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>a message without any attributes will be logged
provided the <code class="literal">audit</code> flag is not specified
</p></li><li class="listitem"><p>a message with both the <code class="literal">audit</code> and
<code class="literal">sensitive</code> attributes will be logged only if
the filter specifies the <code class="literal">audit</code> flag, and either
the <code class="literal">sensitive</code> flag is given or
<span class="property">LOG_SENSITIVE</span> is enabled
</p></li></ul></div><p>
</p><p>If the directive's value begins with the keyword <code class="literal">any</code>,
the filter matches any source, so there is no
<em class="replaceable"><code>name</code></em> and the modifier flags related to matching
<em class="replaceable"><code>name</code></em> are ignored.
</p><p><a name="logging_levels"></a>In order of increasing importance
and decreasing amount of detail,
<em class="replaceable"><code>level</code></em> is one of the following
case-insensitive keywords:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">trace</code> (or <code class="literal">tracing</code>,
least important messages)
</p></li><li class="listitem"><p>
<code class="literal">debug</code> (or <code class="literal">debugging</code>)
</p></li><li class="listitem"><p>
<code class="literal">info</code>
</p></li><li class="listitem"><p>
<code class="literal">notice</code> (or <code class="literal">notices</code>)
</p></li><li class="listitem"><p>
<code class="literal">warn</code>
(or <code class="literal">warning</code> or <code class="literal">warnings</code>)
</p></li><li class="listitem"><p>
<code class="literal">error</code> (or <code class="literal">errors</code>)
</p></li><li class="listitem"><p>
<code class="literal">critical</code> (or <code class="literal">crit</code>)
</p></li><li class="listitem"><p>
<code class="literal">alert</code> (or <code class="literal">alerts</code>)
</p></li><li class="listitem"><p>
<code class="literal">emerg</code> (or <code class="literal">emergency</code>,
most important messages)
</p></li></ul></div><p>
</p><p>Any log message having a lower importance than
<em class="replaceable"><code>level</code></em> will not satisfy the filter.
If the logging level is set to <code class="literal">info</code>, for example,
messages having a lower level
(<code class="literal">debug</code> and <code class="literal">trace</code>)
will not be recorded.
These levels are intended
to have semantics similar to those of the logging levels used
by <span class="command"><strong>Apache</strong></span> and
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=syslog&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">syslog(3)</a>.
</p><p>The <em class="replaceable"><code>file</code></em> field, which is optional,
is used instead of (or in addition to) <span class="property">LOG_FILE</span> and
interpolation is performed in the same way.
If <em class="replaceable"><code>file</code></em> is <code class="literal">syslog</code>,
all messages matching the filter will be written using
<code class="function">syslog(3)</code>
instead of to <span class="property">LOG_FILE</span>.
If <em class="replaceable"><code>file</code></em> is prefixed with a '<code class="literal">+</code>',
output will be written to both <span class="property">LOG_FILE</span> and the
expansion of <em class="replaceable"><code>file</code></em>; if it is prefixed with
nothing or <code class="literal">-</code>, the default behaviour results;
the initial character can be escaped using a backslash.
In some situations, using <span class="devicefile">/dev/null</span> for
<em class="replaceable"><code>file</code></em> is useful to discard unhelpful messages.
</p><p>Without regard to how <span class="property">LOG_LEVEL</span> and
<span class="property">LOG_SENSITIVE</span> are configured, this directive
says that all messages generated by any function located within the
<span class="command"><strong>DACS</strong></span> source file named <code class="filename">crypto.c</code>
having a level of at least <code class="literal">debug</code>, should be logged,
including those marked as <code class="literal">sensitive</code>:
</p><pre class="programlisting">
LOG_FILTER 'filename exact,sensitive debug crypto.c'
</pre><p>
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>The directive:
</p><pre class="programlisting">
LOG_FILTER 'any audit trace +syslog'
</pre><p>
causes all log messages with the <code class="literal">audit</code> modifier having
level <code class="literal">trace</code> or higher to be written to both
<code class="function">syslog(3)</code>
and <span class="property">LOG_FILE</span>.
If you want to use the <code class="literal">syslog</code> feature in this way,
you will need a section in the
<code class="function">syslog(3)</code> configuration
file (typically <code class="filename">/etc/syslog.conf</code>) that looks
something like the following, depending on the flavour of
<code class="function">syslog(3)</code> that your system uses:
</p><pre class="programlisting">
!dacs
*.* /usr/local/dacs/logs/audit_log
</pre><p>
</p><p>The following directive is similar except that it causes log
messages classified
as either <code class="literal">audit</code> or <code class="literal">sensitive</code>
(or both) to be written to both <span class="property">LOG_FILE</span> and
the file <code class="filename">logs/Audit_log</code>,
relative to the root of the <span class="command"><strong>DACS</strong></span> installation directory:
</p><pre class="screen">
LOG_FILTER 'any audit,sensitive TRACE +%bD/logs/Audit_log'
</pre><p>
By removing the '<code class="literal">+</code>' character, the log messages would
not be written to <span class="property">LOG_FILE</span>.
</p></div><p>Please refer to <a class="ulink" href="dacs.1.html#logging" target="_top">dacs(1)</a>
for general information about logging.
</p></dd><dt><span class="term"><a name="LOG_FORMAT"></a>
<span class="property">LOG_FORMAT</span> (Optional1)</span></dt><dd><p>This directive is used to specify the format of
the string that prefixes log messages produced by <span class="command"><strong>DACS</strong></span>.
Interpolation is controlled by <code class="function">printf</code>-like
format specifiers, as follows:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">%%</code></span></dt><dd><p>Insert a literal percent character
</p></dd><dt><span class="term"><code class="literal">%a</code></span></dt><dd><p>Insert the application name,
which is typically the basename of <code class="varname">argv[0]</code>.
</p></dd><dt><span class="term"><code class="literal">%c</code></span></dt><dd><p>Insert the value of a per-process message counter,
which is then incremented.
</p></dd><dt><span class="term"><code class="literal">%F</code></span></dt><dd><p>Insert event descriptor flags, which indicate whether
the message is an audit event ("<code class="literal">A</code>"),
a potentially sensitive event ("<code class="literal">S</code>"),
a user event ("<code class="literal">U</code>"),
or a normal event ("<code class="literal">-</code>").
</p></dd><dt><span class="term"><code class="literal">%fn</code></span></dt><dd><p>Interpolate the federation name.
</p></dd><dt><span class="term"><code class="literal">%fd</code></span></dt><dd><p>Interpolate the federation domain.
</p></dd><dt><span class="term"><code class="literal">%j</code></span></dt><dd><p>Interpolate the jurisdiction name.
</p></dd><dt><span class="term"><code class="literal">%l</code></span></dt><dd><p>Interpolate the log level of the message.
</p></dd><dt><span class="term"><code class="literal">%p</code></span></dt><dd><p>Interpolate the process id of the process generating
the message.
</p></dd><dt><span class="term"><code class="literal">%sF</code></span></dt><dd><p>Interpolate the name of the function generating the message.
</p></dd><dt><span class="term"><code class="literal">%sf</code></span></dt><dd><p>Interpolate the name of the file generating the message.
</p></dd><dt><span class="term"><code class="literal">%sl</code></span></dt><dd><p>Interpolate the line number within the file that is
generating the message.
</p></dd><dt><span class="term"><code class="literal">%sm</code></span></dt><dd><p>Interpolate the name of the module generating the message.
</p></dd><dt><span class="term"><code class="literal">%sp</code></span></dt><dd><p>Interpolate the name of the program generating the message.
</p></dd><dt><span class="term"><code class="literal">%t</code></span></dt><dd><p>Interpolate the current time and date.
</p></dd></dl></div><p>
</p><p>If a <code class="literal">%</code> is followed by any other character,
that character is printed.
Other characters in the format specifier are interpolated verbatim.
If a requested value is not available, nothing is interpolated.
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>When debugging, it is often helpful to compare log messages
produced when slightly different configurations are used to service a
given request.
With the default prefix, log messages tend to be unique.
To make it easier to compare two sequences of log messages (e.g., using
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=diff&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">diff(1)</a>),
append a special character (such as a tab) or a readily distinguished
character string to the <span class="property">LOG_FORMAT</span> format string.
This will simplify stripping the prefix from log messages
(e.g., using
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=sed&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">sed(1)</a>).
Alternatively,
set an empty prefix string,
or write a conditional directive that eliminates the prefix
only when debugging.
</p></div></dd><dt><span class="term"><a name="LOG_LEVEL"></a>
<span class="property">LOG_LEVEL</span> (Optional1)</span></dt><dd><p>This directive specifies the minimum default
logging level in effect - log messages less important than this will
be discarded.
For example, if <span class="property">LOG_LEVEL</span> is <code class="literal">warn</code>,
only log message of that level or more important will be written
and all others will be discarded.
If there is an applicable <a class="ulink" href="#LOG_FILTER" target="_top">LOG_FILTER</a> directive
it overrides this behaviour, however.
</p><p>Briefly, in order of increasing importance, the names of the
levels are: <code class="literal">trace</code>, <code class="literal">debug</code>,
<code class="literal">info</code>, <code class="literal">notice</code>, <code class="literal">warn</code>,
<code class="literal">error</code>, <code class="literal">critical</code>, <code class="literal">alert</code>,
and <code class="literal">emerg</code>.
The <code class="literal">trace</code> logging level emits the most detail
and the <code class="literal">emerg</code> level emits the least.
Refer to the <a class="ulink" href="#LOG_FILTER" target="_top">LOG_FILTER</a> directive
for additional information.
</p><p>The <span class="property">LOG_LEVEL</span> overrides the compile-time default,
which is obtained using the <span class="symbol">LOG_DEFAULT_LEVEL</span> symbol.
</p><p>By default, informational log messages are emitted almost immediately
when most <span class="command"><strong>DACS</strong></span> web services begin execution.
To suppress these messages, without regard to any other logging configuration,
build <span class="command"><strong>DACS</strong></span> with
<a class="ulink" href="dacs.install.7.html#build_flag_--enable-hush-startup-logging" target="_top">--enable-hush-startup-logging</a>.
</p><p>The "verbose" command line flag (<code class="option">-v</code>)
or the <span class="property">VERBOSE_LEVEL</span> directive
overrides this directive, which are in turn overridden by the
<em class="parameter"><code>-t</code></em>
command line flag ("trace") or the
<span class="property">TRACE_LEVEL</span> directive. A verbose level of one
is equivalent to the info level; a verbose level greater than one is
equivalent to the debug level. Enabling a trace level, with any value,
is equivalent to requesting the trace logging level.
</p><p>Also see
<a class="ulink" href="dacs_acs.8.html#debug_dacs" target="_top">debug_dacs</a>.
</p></dd><dt><span class="term"><a name="LOG_SENSITIVE"></a>
<span class="property">LOG_SENSITIVE</span> (Optional1)</span></dt><dd><p>This directive determines the default behaviour for logging
messages with the <code class="literal">sensitive</code> attribute.
It may have the values "<code class="literal">yes</code>"
(to enable logging sensitive messages) or "<code class="literal">no</code>"
(the default, which discards such messages).
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note22"></a>Note</h3><p>Sensitive
messages may include passwords and other authentication material that
should remain private.
This directive will not suppress potentially sensitive messages
generated by third-party support packages
(e.g., <span class="command"><strong>Samba</strong></span> or <span class="command"><strong>OpenLDAP</strong></span>),
<span class="command"><strong>Apache</strong></span> (including <code class="function">mod_auth_dacs</code>),
or the operating system.
For example, requests for CGI programs invoked using the <code class="literal">GET</code>
method will be logged in the <span class="command"><strong>Apache</strong></span>
<code class="literal">Access Log</code>, and the request's query string will typically
be printed; password parameters may be present in the log
(see
<a class="ulink" href="http://httpd.apache.org/docs/2.2/mod/mod_log_config.html" target="_top">mod_log_config</a>
for details of how to change the log format.
If sensitive messages are being logged, make doubly-sure that log files
have appropriate permissions.
Also, unencrypted logging messages directed over a network
(e.g., through
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=syslog&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">syslog(3)</a>)
may be visible to an attacker.
</p></div><p>
</p></dd><dt><span class="term"><a name="NAME_COMPARE"></a>
<span class="property">NAME_COMPARE</span> (Optional1)</span></dt><dd><p>This directive sets the default method used to compare
<span class="command"><strong>DACS</strong></span> names in various contexts.
Ordinarily, federation, jurisdiction, usernames, and group names
are compared case-sensitively.
If the value of this directive is (case-insensitively) <code class="literal">case</code>,
then case-sensitive comparisons are used;
if its value is <code class="literal">nocase</code>,
case-insensitive comparisons are used;
if its value is <code class="literal">default</code>,
then the application default (either <code class="literal">case</code> or the value
selected by the application) is used.
This directive can be overridden on a case-by-case basis (pun intended);
refer to the <code class="function">user()</code> function
(<a class="ulink" href="dacs.exprs.5.html" target="_top">dacs.exprs(5)</a>) for details.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security9"></a>Security</h3><p>The selected comparison method applies to
<span class="emphasis"><em>all</em></span> components of <span class="command"><strong>DACS</strong></span> names;
if this is not desired, the <code class="function">strtr()</code> function
might be helpful.
Note that this directive does not alter the <span class="command"><strong>DACS</strong></span>
name determined by authentication, only the way the name is compared.
While it's unlikely (and bad practice) for federation names
(or jurisdiction names)
to differ only in their case, it is not unusual for usernames
to be treated case-insensitively for authentication purposes and for this
reason this feature should be used with care.
When case-insensitive comparisons are used, the usernames
<code class="literal">bob</code> and <code class="literal">BOB</code> will be considered to
be equivalent, for example;
sometimes this is useful but it can also be a security hole,
depending on how authentication is configured.
</p><p>Changing the comparison method from case-insensitive
back to case-sensitive may have undesirable consequences;
identities that were formerly equivalent might suddenly become distinct,
which at the very least may confuse users.
</p><p>The recommended practice is to not define
<span class="property">NAME_COMPARE</span> or set it to <code class="literal">case</code>
because of its system-wide effects.
When needed, use the <code class="function">user()</code> function with an
appropriate comparison method argument.
</p></div><p>
</p></dd><dt><span class="term"><a name="NOTICES_ACCEPT_HANDLER"></a>
<span class="property">NOTICES_ACCEPT_HANDLER</span> (Optional1)</span></dt><dd><p>This directive provides a URL (absolute or relative)
to which a user agent will be redirected by the notice acknowledgement handler
after a positive acknowledgement to a notice has
been received (i.e., when the notice or notices were "accepted"),
but only if it is not possible to redirect the user agent to the
request that initiated notice acknowledgement processing (e.g., if that
request used the <code class="literal">POST</code> method).
If not provided, a default HTML page will be returned.
</p></dd><dt><span class="term"><a name="NOTICES_ACK_HANDLER"></a>
<span class="property">NOTICES_ACK_HANDLER</span> (Optional1)</span></dt><dd><p>This directive provides the URL of the notice
acknowledgement handler, which is the program that receives a user's
response to a request to acknowledge one or more notices.
If not provided or if it is the empty string,
the notice presentation handler should assume that it
must also act as the notice acknowledgement handler.
</p></dd><dt><span class="term"><a name="NOTICES_DECLINE_HANDLER"></a>
<span class="property">NOTICES_DECLINE_HANDLER</span> (Optional1)</span></dt><dd><p>This directive provides a URL (absolute or relative) to
which a user agent will be redirected by the notice acknowledgement handler
after a negative acknowledgement to a notice
has been received (i.e., when the notice or notices were "declined").
If not provided, a default HTML page will be returned.
</p></dd><dt><span class="term"><a name="NOTICES_NAT_NAME_PREFIX"></a>
<span class="property">NOTICES_NAT_NAME_PREFIX</span> (Optional1)</span></dt><dd><p>The default prefix of the name of the HTTP cookie bearing a
notice acknowledgement token is "<code class="literal">NAT-DACS</code>".
This directive can be used to override the default.
</p></dd><dt><span class="term"><a name="NOTICES_SECURE_HANDLER"></a>
<span class="property">NOTICES_SECURE_HANDLER</span> (Optional1)</span></dt><dd><p>By default,
<a class="ulink" href="dacs_notices.8.html" target="_top">dacs_notices(8)</a>
takes steps to
prevent attempts to simply ask for notice acknowledgement tokens
(NATs), effectively bypassing having to see notices.
If the value of this directive is "<code class="literal">no</code>", however,
these steps will be disabled.
Please refer to the description of <span class="command"><strong>dacs_notices</strong></span>'
<a class="ulink" href="dacs_notices.8.html#secure_mode" target="_top">Secure Mode</a> of
operation.
</p></dd><dt><span class="term"><a name="NOTICES_WORKFLOW_LIFETIME_SECS"></a>
<span class="property">NOTICES_WORKFLOW_LIFETIME_SECS</span> (Optional1)</span></dt><dd><p>By default, a secure notice acknowledgement workflow
must complete within 120 seconds.
This directive can be used to specify an unsigned integer value that will
override the default.
</p></dd><dt><span class="term"><a name="PAMD_HOST"></a>
<span class="property">PAMD_HOST</span> (Optional1)</span></dt><dd><p>When
<a class="ulink" href="dacs_authenticate.8.html#local_pam_authenticate" target="_top">local_pam_authenticate</a>
is used, this directive is required to specify the domain name or IP address
of the host where <a class="ulink" href="pamd.8.html" target="_top">pamd(8)</a> is executed.
</p></dd><dt><span class="term"><a name="PAMD_PORT"></a>
<span class="property">PAMD_PORT</span> (Optional1)</span></dt><dd><p>When
<a class="ulink" href="dacs_authenticate.8.html#local_pam_authenticate" target="_top">local_pam_authenticate</a>
is used, this may be used to specify the port number or service name on
<span class="property">PAMD_HOST</span> where the
<a class="ulink" href="pamd.8.html" target="_top">pamd(8)</a> server accepts connections.
This directive can be overridden on the <span class="command"><strong>pamd</strong></span> command line.
If no value is explicitly specified, programs will use the compile-time
symbol <span class="symbol">PAMD_SERVICE_NAME</span>
(by default, "<code class="literal">dacs-pamd</code>"), which assumes that
<code class="filename">/etc/services</code> has been configured accordingly.
</p></dd><dt><span class="term"><a name="PASSWORD_CONSTRAINTS"></a>
<span class="property">PASSWORD_CONSTRAINTS</span> (Optional1)</span></dt><dd><p>This directive describes requirements that must
be met by new passwords created by
<a class="ulink" href="dacs_passwd.8.html" target="_top">dacs_passwd(8)</a>,
other than when used by a <span class="command"><strong>DACS</strong></span> administrator.
In other situations, where a <span class="command"><strong>DACS</strong></span> administrator
must be running the program (such as with
<a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a> or
<a class="ulink" href="dacstoken.1.html" target="_top">dacstoken(1)</a>), a warning message
is produced if a new, non-conforming password or PIN is set but the
password can still be used.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="important2"></a>Important</h3><p>Each system usually imposes its own constraints on the characters
that may be used in password, minimum and maximum password lengths, and so on.
These constraints are external to <span class="command"><strong>DACS</strong></span>.
With respect to the <em class="parameter"><code>PASSWORD</code></em> parameter passed to
<span class="command"><strong>DACS</strong></span> web services
(e.g., <a class="ulink" href="dacs_authenticate.8.html#local_ldap_authenticate" target="_top">local_ldap_authenticate</a>)
and used with <span class="command"><strong>DACS</strong></span> accounts
(e.g., <a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a>),
it is safest to stick to printable ASCII characters.
A compile-time maximum length of <code class="constant">128</code> characters is imposed
on the <em class="parameter"><code>PASSWORD</code></em> parameter.
Limits are also imposed on the <em class="parameter"><code>USERNAME</code></em>
and <em class="parameter"><code>AUXILIARY</code></em> parameters
(see
<a class="ulink" href="dacs_authenticate.8.html#web_service_arguments" target="_top">Web Service Arguments</a>).
These limits are more-or-less arbitrary but necessary.
</p></div><p>This directive's syntax is also used by the
<a class="ulink" href="dacs_authenticate.8.html#PASSWORD_AUDIT" target="_top">PASSWORD_AUDIT</a>
directive, which may appear in an <code class="literal">Auth</code> clause.
</p><p>The format of the constraint string is a set of zero or more
comma-separated terms.
Each term consists of an unsigned integer (zero or greater) followed
immediately by a single character (case sensitive) that indicates a
<span class="emphasis"><em>constraint type</em></span>:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">L</code> refers to the minimum length of a
password, in characters;
</p></li><li class="listitem"><p><code class="literal">C</code> is the minimum number of characters
<span class="emphasis"><em>from each case</em></span>
that must be present (e.g., <code class="literal">3C</code> means
a password must have at least three upper case characters
<span class="emphasis"><em>and</em></span> three lower case characters);
</p></li><li class="listitem"><p><code class="literal">D</code> is the minimum number of digits
(0-9) that must be present;
</p></li><li class="listitem"><p>and <code class="literal">P</code> is the minimum number of punctuation
characters
(see <a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=ispunct&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">ispunct(3)</a>)
that must be present.
</p></li></ul></div><p>
</p><p>A constraint type may not appear more than once.
Not all constraint types need to be specified.
If this directive is not given, or is the empty string, or the word
"<code class="literal">none</code>" (case insensitive),
a minimum password length of any six characters is used.
If a constraint type is missing, a minimum of zero is used.
In no event is a password of fewer than six characters allowed for a
non-administrator, however.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security91"></a>Security</h3><p>No check is made
for constraints that are impossible to satisfy.
</p></div><p>
</p><p>For example, the following directive says that passwords must
be at least eight characters long and include at least one digit and
one upper case and one lower case character, with no punctuation characters
required:
</p><pre class="screen">
PASSWORD_CONSTRAINTS "8L,1D,1C,0P"
</pre><p>
</p></dd><dt><span class="term"><a name="PASSWORD_DIGEST"></a>
<span class="property">PASSWORD_DIGEST</span> (Optional1)</span></dt><dd><p>This directive specifies the cryptographic hash function
or key derivation function used by
<a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a>,
<a class="ulink" href="dacs_passwd.8.html" target="_top">dacs_passwd(8)</a>,
<a class="ulink" href="dacstoken.1.html" target="_top">dacstoken(1)</a>,
<a class="ulink" href="dacs_token.8.html" target="_top">dacs_token(8)</a>, and
<a class="ulink" href="dacs_admin.8.html" target="_top">dacs_admin(8)</a>
for computing password digests.
The same specification syntax described here is used in other contexts
throughout <span class="command"><strong>DACS</strong></span> where a digest function needs to
be parameterized.
Not all digest functions can be used in all contexts, however
(see <a class="ulink" href="dacs.1.html#digests-arg" target="_top">dacs(1)</a>).
By default,
<code class="literal">SHA-512</code> is used.
Prior to version <span class="version">1.4.34</span>,
the default was <code class="literal">SHA-1</code>.
</p><p>In most cases only the name of the function is required,
but functions that are parameterized (e.g., <code class="literal">SCRYPT</code>)
require <span class="emphasis"><em>all</em></span> configurable variables to be
provided - there are no defaults.
</p><p>The syntax for specifying a cryptographic digest is as follows:
</p><pre class="screen">
<em class="replaceable"><code>digest-descriptor</code></em> ::= <em class="replaceable"><code>dn</code></em> <em class="replaceable"><code>ws</code></em>* [ '[' <em class="replaceable"><code>arg-list</code></em> ']' ]
<em class="replaceable"><code>arg-list</code></em> ::= <em class="replaceable"><code>name</code></em> '=' <em class="replaceable"><code>value</code></em> [, <em class="replaceable"><code>arg-list</code></em> ]
</pre><p>
A <em class="replaceable"><code>digest-descriptor</code></em>
is a digest name (<em class="replaceable"><code>dn</code></em>),
optionally followed by whitespace,
optionally followed by an argument string
(<em class="replaceable"><code>arg-list</code></em>) within square brackets.
The argument string consists of one or more
<code class="literal">name=value</code> pairs,
separated by a comma.
The order of the pairs is not significant.
A <em class="replaceable"><code>name</code></em> may not appear more than once
and an unrecognized parameter name is not allowed.
Nothing can follow the closing square bracket.
Whitespace may precede a <em class="replaceable"><code>name</code></em>,
but everything following the '<code class="literal">=</code>' is part of the value.
The <em class="replaceable"><code>value</code></em> ends at a comma or the closing bracket,
so embedded whitespace is possible (but should be avoided).
Whitespace following a comma is ignored.
A <em class="replaceable"><code>value</code></em> may be surrounded by single
or double quotes, but escaping is not allowed.
Examples:
</p><pre class="programlisting">
PASSWORD_DIGEST "scrypt[N=1024, r='8', p=16, dklen=32]"
PASSWORD_DIGEST "sha512/t[t=72]"
PASSWORD_DIGEST "pbkdf2[a=sha256,count=4098, dklen=20]"
</pre><p>
The digest name is matched against available password digest functions
case-insensitively.
Non-consecutive hyphens, underscores, and slashes in the digest name
are treated as equivalent separators.
A separator may be omitted if doing so would not join two digits.
An initial or trailing separator is disallowed.
For example:
</p><pre class="programlisting">
"<code class="literal">Sha224</code>" matches "<code class="literal">SHA-224</code>"
"<code class="literal">SHA/512</code>" matches "<code class="literal">SHA-512</code>"
"<code class="literal">pbkdf2sha512</code>" matches "<code class="literal">PBKDF2-SHA512</code>"
</pre><p>
Use the
<code class="literal">digests</code> subcommand of
<a class="ulink" href="dacs.1.html#digests-arg" target="_top">dacs(1)</a>
to list available algorithms and
<code class="literal">checkdigest</code>
to validate a digest descriptor:
</p><pre class="programlisting">
% dacs digests
% dacs checkdigest "pbkdf2[a=sha256,count=80000,dklen=32]"
</pre><p>
</p><p>The following cryptographic digest algorithms are available:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">CRYPT</code></span></dt><dd><p>for the Unix
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=crypt&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">crypt(3)</a>
function
</p></dd><dt><span class="term"><code class="literal">MD5</code></span></dt><dd><p>for the
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc1321.txt" target="_top">MD5 function</a>
(deprecated).
</p></dd><dt><a name="SHA_functions"></a><span class="term"><code class="literal">SHA-1</code><br></span><span class="term"><code class="literal">SHA-224</code><br></span><span class="term"><code class="literal">SHA-256</code><br></span><span class="term"><code class="literal">SHA-384</code><br></span><span class="term"><code class="literal">SHA-512</code><br></span><span class="term"><code class="literal">SHA-512/224</code><br></span><span class="term"><code class="literal">SHA-512/256</code><br></span><span class="term"><code class="literal">SHA-512/t</code></span></dt><dd><p>for one of the variants of the Secure Hash Algorithm
functions
(<a class="ulink" href="http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf" target="_top">FIPS 180-4</a>).
</p></dd><dt><a name="SHA3_functions"></a><span class="term"><code class="literal">SHA3-224</code><br></span><span class="term"><code class="literal">SHA3-256</code><br></span><span class="term"><code class="literal">SHA3-384</code><br></span><span class="term"><code class="literal">SHA3-512</code></span></dt><dd><p>for one of the variants of the Secure Hash Algorithm-3
functions
(<a class="ulink" href="http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf" target="_top">FIPS PUB 202, August/2015</a>).
</p></dd></dl></div><p>
</p><p>The following password-based key derivation algorithms are available:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ARGON2</code></span></dt><dd><p>for the
<a class="ulink" href="https://en.wikipedia.org/wiki/Argon2" target="_top">Argon2</a>
memory-hard password-based key derivation function.
Required parameters with suggested minimum values:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">y</code></span></dt><dd><p>The algorithm flavour,
which must be
"<code class="literal">i</code>" for <code class="literal">Argon2i</code> or
"<code class="literal">d</code>" for <code class="literal">Argon2d</code>
(suggested: "<code class="literal">i</code>").
</p></dd><dt><span class="term"><code class="literal">v</code></span></dt><dd><p>The version identifier, in decimal, which currently must
be <code class="constant">19</code>.
</p></dd><dt><span class="term"><code class="literal">m</code></span></dt><dd><p>The memory requirement, in KB
(suggested: <code class="constant">32</code>).
</p></dd><dt><span class="term"><code class="literal">t</code></span></dt><dd><p>The iteration count
(suggested: <code class="constant">3</code>).
</p></dd><dt><span class="term"><code class="literal">p</code></span></dt><dd><p>The amount of requested parallelism, referred to as "lanes"
(suggested: <code class="constant">4</code>).
</p></dd><dt><span class="term"><code class="literal">T</code></span></dt><dd><p>The output length, in bytes
(suggested: <code class="constant">32</code>).
</p></dd><dt><span class="term"><code class="literal">X</code></span></dt><dd><p>The associated data, encoded as a hex string.
Use the empty string if there is no associated data.
</p></dd><dt><span class="term"><code class="literal">S</code></span></dt><dd><p>The salt, encoded as a hex string.
In this context,
<span class="emphasis"><em>this must be the empty string</em></span>,
because the salt is stored elsewhere in the password entry.
</p></dd></dl></div><p>
</p><p>
Example:
</p><pre class="screen">
PASSWORD_DIGEST "argon2[y=i,v=19,m=32,t=3,p=4,T=32,X='000102',S='']"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">PBKDF2</code></span></dt><dd><p>for the
<code class="literal">PBKDF2</code> password-based key derivation function
with the internal hash function specified by the first argument.
Required parameters (with suggested minimum values):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">a</code></span></dt><dd><p>The name of the internal hash function,
such as
"<code class="literal">sha1</code>",
"<code class="literal">sha256</code>",
"<code class="literal">sha512</code>",
"<code class="literal">sha3-256</code>", or
"<code class="literal">sha3-512</code>".
</p></dd><dt><span class="term"><code class="literal">count</code></span></dt><dd><p>The iteration count (suggested: <code class="constant">80,000</code>).
</p></dd><dt><span class="term"><code class="literal">dklen</code></span></dt><dd><p>The output length in bytes,
also called the derived key length (suggested: <code class="constant">32</code>).
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><code class="literal">PBKDF2-SHA1</code></span></dt><dd><p>for the
<code class="literal">PBKDF2</code> password-based key derivation function
with <code class="literal">HMAC-SHA1</code> (see
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2898.txt" target="_top">RFC 2898</a>).
This should probably be avoided in preference to
<code class="literal">PBKDF2-SHA256</code> or <code class="literal">PBKDF2-SHA512</code>.
Required parameters (with suggested minimum values):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">count</code></span></dt><dd><p>The iteration count (suggested: <code class="constant">80,000</code>).
</p></dd><dt><span class="term"><code class="literal">dklen</code></span></dt><dd><p>The output length in bytes,
also called the derived key length (suggested: <code class="constant">32</code>).
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><code class="literal">PBKDF2-SHA256</code></span></dt><dd><p>for the
<code class="literal">PBKDF2</code> password-based key derivation function
with <code class="literal">HMAC-SHA256</code>.
Required parameters (with suggested minimum values):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">count</code></span></dt><dd><p>The iteration count (suggested: <code class="constant">80,000</code>).
</p></dd><dt><span class="term"><code class="literal">dklen</code></span></dt><dd><p>The output length in bytes,
also called the derived key length (suggested: <code class="constant">32</code>).
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><code class="literal">PBKDF2-SHA512</code></span></dt><dd><p>for the
<code class="literal">PBKDF2</code> password-based key derivation function
with <code class="literal">HMAC-SHA512</code>.
Required parameters (with suggested minimum values):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">count</code></span></dt><dd><p>The iteration count (suggested: <code class="constant">80,000</code>).
</p></dd><dt><span class="term"><code class="literal">dklen</code></span></dt><dd><p>The output length in bytes,
also called the derived key length (suggested: <code class="constant">64</code>).
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><code class="literal">SCRYPT</code></span></dt><dd><p>for the
<code class="literal">scrypt</code> memory-hard password-based key derivation function,
which uses <code class="literal">PBKDF2-SHA256</code>.
Required parameters (with suggested minimum values):
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">N</code></span></dt><dd><p>CPU/memory cost parameter (suggested: <code class="constant">131,072</code>).
</p></dd><dt><span class="term"><code class="literal">r</code></span></dt><dd><p>Block size parameter (suggested: <code class="constant">8</code>).
</p></dd><dt><span class="term"><code class="literal">p</code></span></dt><dd><p>Parallelization parameter (suggested: <code class="constant">1</code>)
</p></dd><dt><span class="term"><code class="literal">dklen</code></span></dt><dd><p>The output length in bytes,
also called the derived key length (suggested: <code class="constant">32</code>).
</p></dd></dl></div><p>
</p></dd></dl></div><p>
</p><p>The <code class="literal">PBKDF2</code>, <code class="literal">scrypt</code>,
and <code class="literal">Argon2</code>
functions should be carefully parameterized to be computationally
intensive and memory intensive, if applicable,
for the platform on which the password-based authentication module is run.
The goal is to make password hashing unavoidably inefficient.
This makes it more difficult for an attacker that accesses a copy of
a password file to guess passwords because each guess takes longer or requires
more resources than a comparatively efficient algorithm.
For additional information about these algorithms and their parameters,
see <a class="ulink" href="dacs.exprs.5.html#argon2" target="_top">argon2()</a>,
<a class="ulink" href="dacs.exprs.5.html#pbkdf2" target="_top">pbkdf2()</a>,
and <a class="ulink" href="dacs.exprs.5.html#scrypt" target="_top">scrypt()</a>.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security15"></a>Security</h3><p>Apart from using an authentication method stronger than one
based solely on passwords,
it is considered best practice to use a key derivation function such as
<code class="function">pbkdf2</code> or <code class="function">scrypt</code>
rather than a plain cryptographic digest for the
<span class="property">PASSWORD_DIGEST</span>.
</p><p>These key derivation functions are intended to be
inherently inefficient yet as efficient as possible.
They are used for this purpose to provide additional resistance against
brute force methods, even those that employ special hardware,
should an attacker obtain a password file.
But they do not help much if users are allowed to choose weak passwords,
if the key derivation function is not properly parameterized,
or if the function has exploitable properties.
In these cases, it will still not be much of a challenge for an attacker
to determine the original passwords.
On the other hand, if only strong passwords are allowed and a good
cryptographic digest function is used,
a key derivation function is unnecessary.
A key derivation function is most suitable for protecting passwords
that are neither very weak nor particularly strong.
</p><p>Memory-hard functions are a relatively new idea
and many designs have not yet received much scrutiny.
It should also be noted that significantly increasing the memory and CPU
resources needed for each authentication operation could pose a problem for
sites that must be prepared to handle many concurrent sign-ons.
Running several memory-hard functions simultaneously on a server could
cause it to run out of resources,
which may provide an opportunity for denial of service attacks.
</p><p>The selected password digest algorithm and its parameters should
be reviewed periodically.
If changes are made to <span class="property">PASSWORD_DIGEST</span>,
they will apply to new accounts but existing password entries will not
be invalidated,
so it may be necessary to force users to reset their passwords.
</p></div><p>The digest algorithm and parameters used are stored with a
password entry when the password is set or changed.
The algorithm or its parameters can therefore be reconfigured without voiding
any pre-existing password entries.
As processing power continues to increase,
the strength of the configured
<span class="property">PASSWORD_DIGEST</span> should periodically be increased.
An administrator can determine the digest method used for each password entry
(see <a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a>),
and a user that has an entry that employed a relatively weak method
should be asked to re-register his password.
</p><p>The system <code class="function">crypt()</code> function may have
platform-dependent limitations on the number of characters that are significant
in a password or the maximum length of a password,
but all other algorithms use all of the characters and impose no
maximum password length.
</p></dd><dt><span class="term"><a name="PASSWORD_OPS_NEED_PASSWORD"></a>
<span class="property">PASSWORD_OPS_NEED_PASSWORD</span> (Optional1)</span></dt><dd><p>Ordinarily,
<a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a>
will not allow password maintenance operations
(other than listing) unless the user has authenticated as an
<a class="ulink" href="#ADMIN_IDENTITY" target="_top">ADMIN_IDENTITY</a>
or provides a valid password for
the username being administered (one that was created by
<a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a>).
If this directive is "<code class="literal">no</code>",
a password is not required and
<span class="command"><strong>dacspasswd</strong></span> will assume that all necessary access
control has already been performed.
</p></dd><dt><span class="term"><a name="PASSWORD_SALT_PREFIX"></a>
<span class="property">PASSWORD_SALT_PREFIX</span> (Optional1)</span></dt><dd><p>This string is prepended to a random salt string used
when creating a digest of a password used by
<span class="command"><strong>DACS</strong></span> in various contexts
(e.g., <a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a>).
This may be of interest when
<a class="ulink" href="#PASSWORD_DIGEST" target="_top">PASSWORD_DIGEST</a>
is <code class="literal">CRYPT</code>
because some versions of
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=crypt&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">crypt(3)</a>
interpret the salt string.
</p></dd><dt><span class="term"><a name="PERMIT_CHAINING"></a>
<span class="property">PERMIT_CHAINING</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>", credentials exported by
<a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a>
anywhere in the federation as a result of a rule
having the <code class="literal">permit_chaining</code> attribute set to
<code class="literal">yes</code> will be honoured at this jurisdiction
for access control purposes.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security10"></a>Security</h3><p>Enabling this feature weakens security because it may allow
misappropriated <span class="command"><strong>DACS</strong></span> identities to be used at a
jurisdiction that has enabled <span class="property">PERMIT_CHAINING</span>.
Use of this feature is discouraged but is sometimes necessary; use with care.
Refer to the description of the <code class="literal">permit_chaining</code>
attribute in <a class="ulink" href="dacs.acls.5.html" target="_top">dacs.acls(5)</a>.
</p></div><p>
</p></dd><dt><span class="term"><a name="PROXY_EXEC_DOCUMENT_ROOT"></a>
<span class="property">PROXY_EXEC_DOCUMENT_ROOT</span> (Optional1)</span></dt><dd><p>Reserved for future use.
</p></dd><dt><span class="term"><a name="PROXY_EXEC_MAPPER_DEFAULT_ACTION"></a>
<span class="property">PROXY_EXEC_MAPPER_DEFAULT_ACTION</span> (Optional1)</span></dt><dd><p>Reserved for future use.
</p></dd><dt><span class="term"><a name="PROXY_EXEC_MAPPER_LOGGING"></a>
<span class="property">PROXY_EXEC_MAPPER_LOGGING</span> (Optional1)</span></dt><dd><p> Reserved for future use.
</p></dd><dt><span class="term"><a name="PROXY_EXEC_MAPPER_LOG_FILE"></a>
<span class="property">PROXY_EXEC_MAPPER_LOG_FILE</span> (Optional1)</span></dt><dd><p>Reserved for future use.
</p></dd><dt><span class="term"><a name="PROXY_EXEC_MAPPER_RULES_FILE"></a>
<span class="property">PROXY_EXEC_MAPPER_RULES_FILE</span> (Optional1)</span></dt><dd><p>Reserved for future use.
</p></dd><dt><span class="term"><a name="PROXY_EXEC_PROG_URI"></a>
<span class="property">PROXY_EXEC_PROG_URI</span> (Optional1)</span></dt><dd><p>Reserved for future use.
</p></dd><dt><span class="term"><a name="RLINK"></a>
<span class="property">RLINK</span> (Optional)</span></dt><dd><p>This directive, which may be repeated,
is used to determine whether the current request includes an
<a class="ulink" href="dacs_acs.8.html#rlinks" target="_top">Rlink</a>.
The <span class="property">RLINK</span> directives are processed in the order in
which they occur.
The value of the directive is a space-separated pair:
the first is an <a class="ulink" href="dacs.exprs.5.html" target="_top">expression</a>
that is evaluated at rule-processing time,
and the second is a
<a class="ulink" href="dacs.conf.5.html#VFS" target="_top">VFS specification</a>
for the location of the Rlinks
(i.e., a <span class="command"><strong>DACS</strong></span> URI, an item type, or an absolute pathname).
If the expression evaluates to a non-empty string:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>the string is assumed to be an
<a class="ulink" href="dacs_acs.8.html#rlinks" target="_top">Rname</a>,
which is relative to the VFS specification,
</p></li><li class="listitem"><p>Rlink processing is enabled for the current request, and
</p></li><li class="listitem"><p>no other <span class="property">RLINK</span> directives are considered
or evaluated.
</p></li></ul></div><p>
If the expression evaluates to the empty string or an error occurs,
the directive is ignored and the next one, if any, is processed.
Example:
</p><pre class="programlisting">
RLINK '"${Args::RNAME:?}" /usr/local/dacs/rlinks'
</pre><p>
In the example above, the directive specifies that if the current request
includes a non-empty argument called <em class="parameter"><code>RNAME</code></em>,
then its value is an Rname, Rlink processing is enabled, and
the Rlink can be found in the
<span class="directory">/usr/local/dacs/rlinks</span> directory.
</p></dd><dt><span class="term"><a name="ROLE_STRING_MAX_LENGTH"></a>
<span class="property">ROLE_STRING_MAX_LENGTH</span> (Optional1)</span></dt><dd><p>A limit is imposed on the
length of the role string returned by any authentication or roles service,
the length of any intermediate role string formed by concatenation during
determination of the role string,
and the length of the final role string, which is used in credentials.
A string that exceeds the limit is invalid and treated as an empty string.
The limit is necessary because credentials (which may contain a role string)
are encapsulated within an HTTP cookie and browsers have
context-dependent and implementation-dependent restrictions on cookie lengths.
This directive is used to set the limit,
overriding a compile-time value of 200 bytes.
Please refer to
<a class="ulink" href="dacs_authenticate.8.html#Roles" target="_top">dacs_authenticate(8)</a>
for additional information about roles.
</p><div class="warning" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Warning</h3><p>A role string that is too long may cause the
user to experience strange and possibly incorrect behaviour from
<span class="command"><strong>DACS</strong></span> because the browser may discard cookies
produced by <span class="command"><strong>DACS</strong></span>.
</p></div><p>
</p></dd><dt><span class="term"><a name="SECURE_MODE"></a>
<span class="property">SECURE_MODE</span> (Optional1)</span></dt><dd><p>This directive causes <span class="command"><strong>DACS</strong></span> to
operate "insecurely" only if its value is
"<code class="literal">no</code>" or "<code class="literal">off</code>"
(case insensitive), otherwise <span class="command"><strong>DACS</strong></span> will use a more secure
mode of operation.
In secure mode, <span class="command"><strong>DACS</strong></span> requires all user interactions to
be through SSL/TLS (HTTPS)
and cookies will have the <code class="literal">secure</code> attribute.
The default is "<code class="literal">yes</code>".
Odd behaviour may result if interactions between <span class="command"><strong>DACS</strong></span>
and a particular client mix <code class="literal">http</code> and
<code class="literal">https</code> requests (such as when handlers are involved).
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security11"></a>Security</h3><p>Always use the secure mode of operation unless you fully understand
the consequences of disabling it.
For <span class="command"><strong>DACS</strong></span> to be a secure system,
secure mode should be disabled only for testing purposes or if all HTTP
traffic is protected by some secure means other than SSL/TLS.
</p></div></dd><dt><span class="term"><a name="SIGNOUT_HANDLER"></a>
<span class="property">SIGNOUT_HANDLER</span> (Optional1)</span></dt><dd><p>When <a class="ulink" href="dacs_signout.8.html" target="_top">dacs_signout(8)</a>
terminates, provided a fatal error was not encountered,
the subsequent action can be customized using this directive.
For instance, the system administrator can ask for the user's browser
to be redirected to a login page.
This capability can also be used to construct a chain of requests
to signout a user from multiple federations.
</p><p>The following syntaxes are supported:
</p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p><code class="literal"><span class="property">SIGNOUT_HANDLER</span> "[url] <em class="replaceable"><code>URL</code></em>"</code>
</p><p>This form will cause <span class="command"><strong>DACS</strong></span> to redirect the client to
the specified URL, which may be a relative or absolute URL.
If the keyword <code class="literal">url</code> is absent,
<em class="replaceable"><code>URL</code></em>
must begin with the four characters <code class="literal">http</code>.
Whether the <code class="literal">GET</code> method is used depends on the
context of the original request.
The URL may contain a properly escaped query string; <span class="command"><strong>DACS</strong></span>
will append the following parameters, URL encoded and in the order given:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>DACS_VERSION</code></em></span></dt><dd><p>The version number of <span class="command"><strong>DACS</strong></span>
(e.g., "<code class="literal">1.4</code>").</p></dd><dt><span class="term"><em class="parameter"><code>DACS_FEDERATION</code></em></span></dt><dd><p>The federation that received the service request,
if available.</p></dd><dt><span class="term"><em class="parameter"><code>DACS_JURISDICTION</code></em></span></dt><dd><p>The jurisdiction that received the service request,
if available.</p></dd><dt><span class="term"><em class="parameter"><code>DACS_SIGNOUT_RESULT</code></em></span></dt><dd><p>The number of credentials (a non-negative integer) that
<a class="ulink" href="dacs_signout.8.html" target="_top">dacs_signout(8)</a>
asked the web browser to delete by setting expired HTTP cookies.
Note that the total number of HTTP cookies set by
<a class="ulink" href="dacs_signout.8.html" target="_top">dacs_signout(8)</a>
could be greater than this number.
</p></dd></dl></div><p>
The following directive will redirect the user's browser to
a relative URL:
</p><pre class="programlisting">
SIGNOUT_HANDLER "url /dacs/handlers/signout_ok.html?FOO=bar"
</pre><p>
</p></li><li class="listitem"><p><code class="literal"><span class="property">SIGNOUT_HANDLER</span> "defaulturl <em class="replaceable"><code>URL</code></em>"</code>
</p><p>This form is like that of the <code class="literal">url</code> syntax
except that a URL given by a
<em class="parameter"><code>DACS_SIGNOUT_HANDLER</code></em> parameter
will be used if it is passed to
<a class="ulink" href="dacs_signout.8.html" target="_top">dacs_signout(8)</a>.
A <em class="parameter"><code>DACS_SIGNOUT_HANDLER</code></em> parameter is ignored in the
other forms of the <span class="property">SIGNOUT_HANDLER</span> directive.
If that parameter is absent,
the URL specified by this directive is used.
As in the <code class="literal">url</code> form,
<span class="command"><strong>DACS</strong></span> will append parameters to the
<em class="parameter"><code>DACS_SIGNOUT_HANDLER</code></em> URL.
Note that the <code class="literal">defaulturl</code> keyword is not optional.
</p></li><li class="listitem"><p><code class="literal"><span class="property">SIGNOUT_HANDLER</span> "[file] <em class="replaceable"><code>full-pathname</code></em>"</code>
</p><p>This form causes the contents of the file named by
<em class="replaceable"><code>full-pathname</code></em> to be returned.
The file must include any header lines it requires, such
as a <span class="property">Content-Type</span> line, a header-terminating blank line,
and then the document content.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note23"></a>Note</h3><p>The
"<code class="literal">full-pathname</code>" usage differs from
the "<code class="literal">local-URL</code>" usage of the
<span class="property">ACS_ERROR_HANDLER</span> directive, though both
elements begin with a slash character; the former specifies the absolute
pathname of a file, while the latter specifies a URL local to the receiving
web server.
To specify a relative URL, use the <code class="literal">url</code> keyword.
</p></div></li><li class="listitem"><p><code class="literal"><span class="property">SIGNOUT_HANDLER</span> "[message] \"<em class="replaceable"><code>message</code></em>\""</code>
</p><p>This form causes the given message, surrounded by escaped double quote
characters, to be returned as HTML.
</p><pre class="programlisting">
SIGNOUT_HANDLER "message \"You're outta here!\""
</pre><p>
</p></li><li class="listitem"><p><code class="literal"><span class="property">SIGNOUT_HANDLER</span> "<code class="literal">credentials"</code></code>
</p><p>This form causes the user's remaining credentials to be displayed as
an HTML document. This is the default behaviour.
</p></li></ol></div><p>The optional keywords are treated case-insensitively.
</p></dd><dt><span class="term"><a name="SSL_PROG"></a>
<span class="property">SSL_PROG</span> (Optional1)</span></dt><dd><p>The full pathname of the command used to provide an
SSL/TLS connection for group information distribution.
Currently, only
<a class="ulink" href="sslclient.1.html" target="_top">sslclient(1)</a>
is supported for this purpose.
</p></dd><dt><span class="term"><a name="SSL_PROG_ARGS"></a>
<span class="property">SSL_PROG_ARGS</span> (Optional1)</span></dt><dd><p>Additional command line arguments to be passed to
<span class="property">SSL_PROG</span>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note24"></a>Note</h3><p>This
directive is "global" in that it applies to all
internal invocations of <span class="property">SSL_PROG</span>.
SSL/TLS options should probably be more flexibly configurable
(e.g., from within <code class="literal">Auth</code> and <code class="literal">Roles</code>
clauses).
</p></div><p>
</p></dd><dt><span class="term"><a name="SSL_PROG_CA_CRT"></a>
<span class="property">SSL_PROG_CA_CRT</span> (Optional1)</span></dt><dd><p>The full pathname of the file containing the CA certificate
shared by this <span class="command"><strong>DACS</strong></span> federation. This is passed to
<span class="property">SSL_PROG</span> so that certificates can be validated.
</p></dd><dt><span class="term"><a name="SSL_PROG_CLIENT_CRT"></a>
<span class="property">SSL_PROG_CLIENT_CRT</span> (Optional1)</span></dt><dd><p>This provides the name of a private key and certificate
chain PEM file. Please refer to
<a class="ulink" href="sslclient.1.html" target="_top">sslclient(1)'s</a>
<code class="option">-ccf</code> flag.
</p></dd><dt><span class="term"><a name="STATUS_LINE"></a>
<span class="property">STATUS_LINE</span> (Optional1)</span></dt><dd><p>
If this directive is set to "<code class="literal">on</code>",
<a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a> will emit a
<a class="ulink" href="dacs_acs.8.html#dacs_status_line" target="_top">DACS-Status-Line</a>
header in the response from the server.
The default value is "<code class="literal">off</code>".
See the description of the
<a class="ulink" href="dacs_acs.8.html#dacs_acs_argument" target="_top">DACS_ACS argument</a>
for additional details.
</p></dd><dt><span class="term"><a name="TEMP_DIRECTORY"></a>
<span class="property">TEMP_DIRECTORY</span> (Optional1)</span></dt><dd><p>A directory where <span class="command"><strong>DACS</strong></span>
can create temporary files.
If the value is not an absolute path, the location is relative to
<a class="ulink" href="#var_dacs_home" target="_top">DACS_HOME</a>.
Lock files, for example, are put in this directory.
If not configured or if this directory does not exist,
a compile-time path (<span class="symbol">DEFAULT_TEMP_DIRECTORY</span>) is used
(currently: <span class="directory">/tmp</span>).
It is always safe to delete the contents of this directory
if <span class="command"><strong>DACS</strong></span> is not running.
Read and write access to this directory must be restricted to
<span class="command"><strong>DACS</strong></span>.
</p></dd><dt><span class="term"><a name="TOKEN_REQUIRES_PIN"></a>
<span class="property">TOKEN_REQUIRES_PIN</span> (Optional1)</span></dt><dd><p>If set to <code class="literal">no</code>,
then <a class="ulink" href="dacstoken.1.html" target="_top">dacstoken(1)</a> does not
require created or imported accounts to have a <acronym class="acronym">PIN</acronym>.
The default value is <code class="literal">yes</code>,
and a <acronym class="acronym">PIN</acronym> is required.
</p></dd><dt><span class="term"><a name="TOKEN_HOTP_ACCEPT_WINDOW"></a>
<span class="property">TOKEN_HOTP_ACCEPT_WINDOW</span> (Optional1)</span></dt><dd><p>When validating or authenticating against a given one-time
password, this is the maximum number of successive counter values to consider,
if necessary, after the expected counter value.
A value of zero disables this search.
If not configured, a compile-time value is used
(currently, <code class="literal">3</code>).
</p></dd><dt><span class="term"><a name="TRACE_LEVEL"></a>
<span class="property">TRACE_LEVEL</span> (Optional1)</span></dt><dd><p>If assigned a non-zero value, tracing is enabled in
various <span class="command"><strong>DACS</strong></span> services.
Larger values will cause more events to be traced. This is intended to give
an indication of the steps a <span class="command"><strong>DACS</strong></span> service takes
during execution for debugging purposes.
Logging information is generally written to the web
server's log file or to a file configured into <span class="command"><strong>DACS</strong></span>
at compile time.
Also see <span class="property">LOG_LEVEL</span> and <span class="property">VERBOSE_LEVEL</span>.
</p></dd><dt><span class="term"><a name="UNAUTH_ROLES"></a>
<span class="property">UNAUTH_ROLES</span> (Optional1)</span></dt><dd><p>This directive is used to assign a
<a class="ulink" href="dacs.1.html#roles" target="_top">role descriptor string</a> to
<span class="emphasis"><em>unauthenticated</em></span> users.
Association with these roles can be tested using the
<a class="ulink" href="dacs.exprs.5.html#user" target="_top">user()</a> predicate.
</p><p>If a jurisdiction configures this directive:
</p><pre class="screen">
UNAUTH_ROLES "anonymous"
</pre><p>
then the following predicates would both return <code class="constant">True</code>
when applied to an unauthenticated user:
</p><pre class="screen">
user("unauth")
user("%:anonymous")
</pre><p>
</p><p>A useful application of this directive is to
classify unauthenticated users based on contextual elements.
Consider this directive:
</p><pre class="screen">
UNAUTH_ROLES from("10.0.0.0/24") ? "user" : ""
</pre><p>
If an unauthenticated user submits a request from a local IP address
between <span class="ipaddress">10.0.0.0</span> and
<span class="ipaddress">10.0.0.255</span>, the user would be
treated as having the role <code class="literal">user</code>,
otherwise the user would have no roles.
This might be used to conveniently grant limited access to "local" users
without them having to authenticate.
A rule could be written to grant access based on having the role
<code class="literal">user</code>, for example, without needing to consider
whether or not the user has authenticated.
</p><p>Unlike roles assigned to credentials,
roles specified in this way are strictly local to the jurisdiction that
configures them.
Some form of coordination is required if different jurisdictions
need to assign the same roles to unauthenticated users.
These roles are not reported by
<a class="ulink" href="dacs_current_credentials.8.html" target="_top">dacs_current_credentials(8)</a>.
</p></dd><dt><span class="term"><a name="UPROXY_APPROVED"></a>
<span class="property">UPROXY_APPROVED</span> (Stack)</span></dt><dd><p>This directive is used by
<a class="ulink" href="dacs_uproxy.8.html" target="_top">dacs_uproxy(8)</a> to enable proxying
to one or more hosts and to configure each of those mappings.
Each directive specifies a member of the "approved list"
(i.e., a host that may be proxied) using the following syntax:
</p><pre class="screen">
[{'http' | 'https'} '://'] <em class="replaceable"><code>hostname</code></em> [:<em class="replaceable"><code>port</code></em>] [<em class="replaceable"><code>path</code></em>]
</pre><p>
</p><p><span class="command"><strong>dacs_uproxy</strong></span> is invoked with a URI with the
following syntax:
</p><pre class="screen">
.../dacs_uproxy/<em class="replaceable"><code>proxied-hostname</code></em>[:<em class="replaceable"><code>proxied-port</code></em>][<em class="replaceable"><code>proxied-path-prefix</code></em>]
</pre><p>
</p><p>A <em class="replaceable"><code>proxied-hostname</code></em> is matched against the
<em class="replaceable"><code>hostname</code></em> of each entry in the list,
according to the stacked directive ordering,
until a (case insensitive) match is found.
If the <em class="replaceable"><code>proxied-hostname</code></em> is followed by
a port number,
that port number must be explicitly specified in a directive for a match
to occur.
If no scheme is specified, <code class="literal">http</code> is used,
regardless of what protocol the <em class="replaceable"><code>port</code></em> may imply.
If a <em class="replaceable"><code>path</code></em> is given,
it is appended to the <em class="replaceable"><code>proxied-path-prefix</code></em>.
</p><p>For example, consider the directives:
</p><pre class="screen">
UPROXY_APPROVED "example.com"
UPROXY_APPROVED "https://foo.example.com"
UPROXY_APPROVED "http://bar.example.com:8080"
UPROXY_APPROVED "https://baz.example.com:8443/some/path"
</pre><p>
A request for the proxied hostname
<span class="domainname">foo.example.com</span>, such as this:
</p><pre class="screen">
.../dacs_uproxy/foo.example.com/a/b/c.cgi
</pre><p>
will be forwarded by <span class="command"><strong>dacs_uproxy</strong></span> as the URI:
</p><pre class="screen">
https://foo.example.com/a/b/c.cgi
</pre><p>
And the proxied request:
</p><pre class="screen">
.../dacs_uproxy/baz.example.com/a/b/c.cgi
</pre><p>
will be forwarded by <span class="command"><strong>dacs_uproxy</strong></span> as the URI:
</p><pre class="screen">
https://baz.example.com:8443/some/path/a/b/c.cgi
</pre><p>
This request would fail because there is no approved entry for
<code class="literal">bar.example.com:80</code>:
</p><pre class="screen">
.../dacs_uproxy/bar.example.com:80/a/b/c.cgi
</pre><p>
</p></dd><dt><span class="term"><a name="VERBOSE_LEVEL"></a>
<span class="property">VERBOSE_LEVEL</span> (Optional1)</span></dt><dd><p>If assigned a non-zero value, debugging output is
enabled in various <span class="command"><strong>DACS</strong></span> services.
Larger values will cause more output to be generated. This is
intended to display input arguments and the values of variables as a
<span class="command"><strong>DACS</strong></span> service is executed, for debugging purposes.
Logging information is generally written to the web server's log file or
to a file configured into <span class="command"><strong>DACS</strong></span> at compile time.
Also see <span class="property">LOG_LEVEL</span> and
<span class="property">TRACE_LEVEL</span>.
</p></dd><dt><span class="term"><a name="VERIFY_IP"></a>
<span class="property">VERIFY_IP</span> (Required1)</span></dt><dd><p>If "<code class="literal">yes</code>",
then the IP address in credentials must exactly match the IP address from
which a service request is made.
For example, if <span class="command"><strong>DACS</strong></span> issued credentials in response to
an authentication request that came from the IP address
<span class="ipaddress">10.0.0.123</span>, then these credentials
will only be considered valid for service requests that come from that
IP address.
If the directive's value is "<code class="literal">no</code>",
this verification is not performed.
Any other value is assumed to be a valid argument to the
<a class="ulink" href="dacs.exprs.5.html#from" target="_top">from()</a> predicate:
</p><pre class="screen">
# Only credentials that were issued to an address on this subnet
# are acceptable
VERIFY_IP "10.0.0.0/24"
</pre><p>
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>Verification might be turned off, for example,
in an environment where a user might legitimately submit service requests
associated with different IP addresses.
Refer to
<a class="ulink" href="dacs_authenticate.8.html#credentials" target="_top">dacs_authenticate(8)</a>
for additional information.
</p></div></dd><dt><span class="term"><a name="VERIFY_UA"></a>
<span class="property">VERIFY_UA</span> (Optional1)</span></dt><dd><p>If "<code class="literal">yes</code>",
then the user agent string presented when authentication occurred
(the <span class="property">USER-AGENT</span> request header, exported by
<span class="command"><strong>Apache</strong></span> as <code class="envar">HTTP_USER_AGENT</code>)
must match the user agent string that is sent with subsequent requests
using those credentials.
This is the default.
If the directive's value is "<code class="literal">no</code>",
this verification is not performed at this jurisdiction
but credentials it produces can still be verified by other jurisdictions.
If the directive's value is "<code class="literal">disable</code>",
the feature is totally disabled at this jurisdiction.
The feature is always disabled for certain internally-generated credentials.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security12"></a>Security</h3><p>In typical use of <span class="command"><strong>DACS</strong></span>, this feature should be
enabled because it makes it somewhat more difficult for misappropriated
<span class="command"><strong>DACS</strong></span> credentials to be used.
It is not a foolproof measure, however, because a sophisticated attacker may
be able to obtain or guess a user agent string and use it with stolen
credentials, although guesses may draw attention by causing log messages
to be emitted.
</p><p>Some user agents, including
<a class="ulink" href="dacshttp.1.html" target="_top">dacshttp(1)</a>,
<span class="command"><strong>Mozilla</strong></span>, <span class="command"><strong>Firefox</strong></span>,
<span class="command"><strong>curl</strong></span>, <span class="command"><strong>wget</strong></span>,
and <span class="command"><strong>Konqueror</strong></span>, allow the user agent string to be set.
Including a random or unusual component in the string will strengthen this
feature.
Also, middleware may be able to take advantage of its ability to send a string
of its choosing in the <span class="property">User-Agent</span> header field.
</p><p>Verification might be turned off, for example,
in proxying situations or if credentials are cached by middleware and
then legitimately used with different user agents.
The feature should be disabled for backward compatibility with
releases earlier than <span class="command"><strong>DACS</strong></span> 1.4.14.
</p></div></dd><dt><span class="term"><a name="VFS"></a>
<span class="property">VFS</span> (Stack)</span></dt><dd><p>These directives are used to configure the
virtual filestore (VFS) subsystem
(see <a class="ulink" href="dacs.vfs.5.html" target="_top">dacs.vfs(5)</a> and
<a class="ulink" href="dacsvfs.1.html" target="_top">dacsvfs(1)</a> for details).
</p><p>The value of this directive
(a <code class="literal">vfs_uri</code>)
has the following syntax:
</p><pre class="programlisting">
vfs_uri -> [ '[' <em class="replaceable"><code>item_type</code></em> ']' ] <em class="replaceable"><code>URI</code></em>
</pre><p>
As specified in
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2396.txt" target="_top">RFC 2396</a> and
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc3986.txt" target="_top">RFC 3986</a>,
the general form of the URI syntax is:
</p><pre class="programlisting">
<em class="replaceable"><code>scheme</code></em> : [ // <em class="replaceable"><code>authority</code></em>] [<em class="replaceable"><code>path</code></em>] [<em class="replaceable"><code>query</code></em>] [<em class="replaceable"><code>fragment</code></em>]
</pre><p>
</p><p>The <em class="replaceable"><code>item_type</code></em>
(see <a class="ulink" href="dacs.1.html#gloss_item_type" target="_top">dacs(1)</a>)
is optional in some cases -
it can usually be omitted if the directive will not be referenced
and if it does not refer to an indexed object.
It is a case-sensitive label that associates this directive with a class
of objects used by <span class="command"><strong>DACS</strong></span>.
Some labels are reserved and have predefined meaning to <span class="command"><strong>DACS</strong></span>;
these are always lowercase;
<a class="ulink" href="dacsconf.1.html" target="_top">dacsconf(1)</a> can list them.
Any label can be defined by a <span class="command"><strong>DACS</strong></span> administrator,
but a reserved item type should only be defined for its intended use;
user-defined item types should therefore include at least one uppercase letter.
For example, here are a few reserved item types:
<code class="literal">passwds</code>
(used by <a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a> and others),
<code class="literal">federation_keys</code> and <code class="literal">jurisdiction_keys</code>
(used by <a class="ulink" href="dacskey.1.html" target="_top">dacskey(1)</a> and others),
<code class="literal">revocations</code>
(used by <a class="ulink" href="dacs.acls.5.html" target="_top">dacs.acls(5)</a> and others), and
<code class="literal">stdin</code>
(used by <a class="ulink" href="dacs.exprs.5.html#get" target="_top">get()</a> and others).
</p><p>Although the <em class="replaceable"><code>scheme</code></em> is case-insensitive,
the canonical form is lowercase.
The <em class="replaceable"><code>authority</code></em>, <em class="replaceable"><code>query</code></em>,
and <em class="replaceable"><code>fragment</code></em> URI components are often absent.
The <em class="replaceable"><code>query</code></em> component is used to specify options.
</p><p>The <em class="replaceable"><code>path</code></em> component of a URI
has the format:
</p><pre class="programlisting">
[ <em class="replaceable"><code>naming_context</code></em> ] [ "," <em class="replaceable"><code>rel-path</code></em> ]
</pre><p>
For paths that have a separate key relative to the naming context,
its start is delimited by a comma.
</p><p>The <em class="replaceable"><code>scheme</code></em> may be:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">dacs-db</code></span></dt><dd><p>A
<a class="ulink" href="http://www.oracle.com/us/products/database/berkeley-db/overview/index.html" target="_top">Berkeley DB</a>,
a hash-based database that manages a collection of objects
within a regular file.
The <em class="replaceable"><code>item_type</code></em> is required because it forms the
initial part of the key.
</p></dd><dt><span class="term"><code class="literal">dacs-ndbm</code></span></dt><dd><p>The Unix
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=dbm&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html" target="_top">dbm(3)</a>
API (includes
<a class="ulink" href="http://www.gnu.org/software/gdbm/gdbm.html" target="_top">GNU gdbm</a>),
which is similar to <code class="literal">dacs-db</code>.
The <em class="replaceable"><code>item_type</code></em> is required because it forms the
initial part of the key.
</p></dd><dt><span class="term"><code class="literal">dacs-fs</code><br></span><span class="term"><code class="literal">fs</code><br></span><span class="term"><code class="literal">file</code></span></dt><dd><p>Files and directories managed through filesystem operations.
Where <em class="replaceable"><code>path</code></em> names a directory,
each key maps to a regular file within that directory.
</p></dd><dt><span class="term"><code class="literal">dacs-sqlite</code></span></dt><dd><p>An
<a class="ulink" href="http://www.sqlite.org" target="_top">SQLite</a> database
that manages a collection of objects within a regular file.
The <em class="replaceable"><code>item_type</code></em> is required because it is used
as the SQL table name.
</p></dd><dt><span class="term"><code class="literal">http</code><br></span><span class="term"><code class="literal">https</code></span></dt><dd><p>HTTP-based object access.
For example,
<span class="domainname">example.com</span> might configure
access to its revocation list like this (with appropriate access controls):
</p><pre class="programlisting">
VFS "[revocations]https://example.com/dacs/revocation_list"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">dacs-kwv</code></span></dt><dd><p>A keyword-value organization
that is managed within a single object associated with another
item type.
In other words, it says that another object, configured with its own
<span class="property">VFS</span> directive, has an internal structure where
each line of the object represents one record.
Each record consists of a keyword, followed by a separator character,
and the value associated with the keyword.
A keyword consists of a sequence of printable, non-whitespace characters.
By default, the separator character is a colon.
(A well-known example of a file having this format is
<code class="filename">/etc/password</code>.)
To specify a different separator, the <code class="literal">vfs_uri</code>
should include the query argument <em class="parameter"><code>field_sep</code></em> whose value
is the separator character to use.
The <em class="replaceable"><code>path</code></em> component gives the name of the
<span class="property">item_type</span> that should be used to manage the underlying
objects.
</p><p>For example, components of <span class="command"><strong>DACS</strong></span> expect
the <code class="literal">passwds</code> item type to be defined.
Taken together, the following pair of directives specify that the plain file
<code class="filename">/usr/local/dacs/passwd</code> consists of keyword-value pairs:
</p><pre class="programlisting">
VFS "[password_file]dacs-fs:/usr/local/dacs/passwd"
VFS "[passwds]dacs-kwv:password_file"
</pre><p>
To specify a space as the separator character instead of the colon
(which is the default), use the directives:
</p><pre class="programlisting">
VFS "[password_file]dacs-fs:/usr/local/dacs/passwd"
VFS "[passwds]dacs-kwv:password_file?field_sep=+"
</pre><p>
Because these are URIs, they must be properly encoded and
the '<code class="literal">+</code>' character represents a space.
If the passwords are to be stored in a Berkeley DB database,
the directive would be:
</p><pre class="programlisting">
VFS "[passwds]dacs-db:/usr/local/dacs/passwd.db"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">dacs-kwv-<em class="replaceable"><code>subscheme</code></em></code></span></dt><dd><p>A concise way of composing the <code class="literal">dacs-kwv</code>
scheme with underlying objects accessed using
<em class="replaceable"><code>subscheme</code></em>.
Currently, <em class="replaceable"><code>subscheme</code></em> can be
<code class="literal">fs</code> (for <code class="literal">dacs-fs</code>),
<code class="literal">http</code>, or <code class="literal">https</code>.
For <code class="literal">fs</code>, the <em class="replaceable"><code>path</code></em> component
is the absolute pathname of a file, its contents having the keyword-value
organization.
For <code class="literal">http</code> and <code class="literal">https</code>,
the <em class="replaceable"><code>path</code></em> component is the remainder of the URL
(i.e., the scheme that specifies the object is implied),
which will be retrieved using the <code class="literal">GET</code>
method, stored and replaced using the <code class="literal">PUT</code> method, deleted
using the <code class="literal">DELETE</code> method, and
tested for using the <code class="literal">HEAD</code> method.
Note that any options (i.e., a query string) bind to
<em class="replaceable"><code>subscheme</code></em>;
if options for <code class="literal">dacs-kwv</code> are needed,
two separate URIs must be used instead of this method.
</p><p>This configuration directive
is almost equivalent to the pair of directives described in the example above:
</p><pre class="programlisting">
VFS "[passwds]dacs-kwv-fs:/usr/local/dacs/passwd"
</pre><p>
</p><p>The following configuration directive states that the password file
used by
<a class="ulink" href="dacspasswd.1.html" target="_top">dacspasswd(1)</a> is to be accessed
at the URL <span class="url">https://example.com/dacs/passwds</span>
using the standard HTTP methods:
</p><pre class="programlisting">
VFS "[passwds]dacs-kwv-https://example.com/dacs/passwds"
</pre><p>
</p></dd><dt><span class="term"><code class="literal">dacs-vfs</code></span></dt><dd><p>The <span class="command"><strong>DACS</strong></span>
CGI-based VFS service,
<a class="ulink" href="dacs_vfs.8.html" target="_top">dacs_vfs(8)</a>,
which exports VFS operations on VFS objects through a web service.
An item type must be provided and must be configured at the specified
<span class="command"><strong>DACS</strong></span> jurisdiction using any of the supported store types
(which means the <code class="literal">dacs-vfs</code> scheme can be used to access
items stored in a remote regular file, hash-based database, and so on).
</p><p>For example, this directive causes <span class="command"><strong>DACS</strong></span> to look
for password entries used by
<a class="ulink" href="dacs_authenticate.8.html#local_passwd_authenticate" target="_top">local_passwd_authenticate</a>
to be accessed through the virtual filestore at
<span class="domainname">example.com</span>:
</p><pre class="programlisting">
VFS "[passwds]dacs-vfs:https://example.com/cgi-bin/dacs/dacs_vfs"
</pre><p>
</p></dd></dl></div><p>
</p><p>A <code class="literal">vfs-ref</code> is a reference to a virtual filestore
definition and can be a <code class="literal">vfs_uri</code> or
an <code class="literal">item_type</code> defined by a
<span class="property">VFS</span> directive.
In some situations it can also be an absolute pathname.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note25"></a>Note</h3><p>At present,
the VFS does not implement much in the way of concurrency control.
Some <span class="command"><strong>DACS</strong></span> components
use coarse-grained locking to ensure that only a single user can access
resources, however, and databases may implement their own concurrency
control.
Only a few of these resources are not used in a read-only fashion;
administrators should adopt appropriate data management practices for them
to ensure concurrent updates cannot occur.
</p></div></dd><dt><span class="term"><a name="XSD_BASE_URL"></a>
<span class="property">XSD_BASE_URL</span> (Optional1)</span></dt><dd><p>When <span class="command"><strong>DACS</strong></span> services are asked to send
an XML Schema response
(i.e., they are passed the argument <code class="literal">FORMAT=XMLSCHEMA</code>) and
this directive is configured, services will emit
<code class="literal">xmlns:xsi</code> and
<code class="literal">xsi:schemaLocation</code> attributes, the former having
a compile-time value
(e.g., <code class="literal">http://www.w3.org/2001/XMLSchema-instance</code>)
and the latter being a pair, the first having the same value as the
value of the <code class="literal">xmlns</code> attribute and the second having a
value derived from the <span class="property">XSD_BASE_URL</span> directive; e.g.,
</p><pre class="programlisting">
<foo xmlns="http://example.com/dacs/v1.4"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://example.com/dacs/v1.4
http://example.com/dacs/dtd-xsd/foo.xsd">
</pre><p>
If <span class="property">XSD_BASE_URL</span> is
not configured, only the default <code class="literal">xmlns</code> attribute is emitted.
</p></dd></dl></div></div></div><div class="refsect2"><a name="auth_clause"></a><h3>The <code class="literal">Auth</code> Clause</h3><p>Each <code class="literal">Auth</code> clause configures an authentication module.
The <code class="literal">Auth</code> clause and its directives are described in
<a class="ulink" href="dacs_authenticate.8.html#auth_clause" target="_top">dacs_authenticate(8)</a>.
</p><p>Note that the order of these clauses is significant - they are processed
in the order in which they appear in the applicable configuration section.
</p></div><div class="refsect2"><a name="idm4294"></a><h3>The <code class="literal">Roles</code> Clause</h3><p>Each <code class="literal">Roles</code> clause configures a roles module.
<code class="literal">Roles</code> clause and its directives are described in
<a class="ulink" href="dacs_authenticate.8.html#roles_clause" target="_top">dacs_authenticate(8)</a>.
</p><p>The clauses are processed in the order in which they appear.
Authentication modules may return roles, to improve efficiency, but
roles are usually obtained through a roles module.
Roles modules are processed only if authentication is successful.
</p></div><div class="refsect2"><a name="idm4302"></a><h3>The <code class="literal">Transfer</code> Clause</h3><p>Each <code class="literal">Transfer</code> clause configures
<a class="ulink" href="dacs_auth_transfer.8.html" target="_top">dacs_auth_transfer(8)</a>
for importing from one or more federations specified within the clause.
The clauses are processed in the order in which they appear.
No clause should apply to more than one initial federation,
although this is not enforced.
</p><p>Each <code class="literal">Transfer</code> element has an <code class="literal">id</code>
attribute.
Its value is merely a label
(an alphabetic followed by zero or more alphanumerics, hyphens, and
underscores)
that allows the clause to be referenced;
the syntax is the same as that of a
<a class="ulink" href="dacs.1.html#naming" target="_top">groupname</a>.
The attribute values must be unique (case-sensitively).
<code class="literal">Transfer</code> clause directives are described in
<a class="ulink" href="dacs_auth_transfer.8.html" target="_top">dacs_auth_transfer(8)</a>.
</p></div><div class="refsect2"><a name="advanced"></a><h3>Advanced Techniques</h3><p>Configuration processing is ordinarily quite straightforward,
but to accommodate more complicated situations it also supports
a few advanced techniques.
</p><div class="refsect3"><a name="config-vars"></a><h4>Configuration Variables</h4><p>After configuration processing determines which directives
have been overridden, those that are in effect have their right hand sides
(which are expressions) evaluated.
These expressions are usually simple strings but they can be any
<span class="command"><strong>DACS</strong></span> expression.
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Tip</h3><p>When configuration processing begins,
variables in the <code class="varname">DACS</code> and <code class="varname">Args</code>
<a class="ulink" href="dacs.exprs.5.html#variables" target="_top">namespaces</a>
can by referenced by configuration directives.
</p></div><p>
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security13"></a>Security</h3><p>The ability to reference an argument during configuration processing
can be useful and powerful when used carefully but since argument
values are completely in the hands of the user constructing a request,
it is a potential security weakness,
particularly in <span class="command"><strong>DACS</strong></span> deployments that are exposed to
the Internet.
</p><p>For example, an argument might be missing or duplicated,
accidentally have a problematic value
(such as containing non-printable or otherwise invalid characters),
or be specifically constructed in an attempt to misconfigure
<span class="command"><strong>DACS</strong></span> to thwart security.
For this reason, variables in the <code class="varname">Args</code> namespace
should be referenced in configuration files only when specifically
indicated in the documentation, or by advanced <span class="command"><strong>DACS</strong></span>
administrators in appropriate circumstances and with caution.
</p></div><p>
</p><p>As each expression is evaluated to determine the value of the directive,
a variable in the <code class="varname">Conf</code> namespace
(see <a class="ulink" href="dacs.exprs.5.html#variables" target="_top">dacs.exprs(5)</a>)
is created and assigned the value, and can then be referenced in
subsequent expressions.
Variables in this namespace can be referenced within access control rules,
permitting rules to be written that depend on how the particular site,
federation, and jurisdiction have been configured.
In addition, during the remainder of the configuration processing stage,
the variable's value can be modified, effectively changing the value
associated with the directive.
After completion of configuration processing, the variables in the
<code class="varname">Conf</code> namespace become read-only.
It is these variables that are displayed by the <code class="option">-vars</code>
option of
<a class="ulink" href="dacsconf.1.html" target="_top">dacsconf(1)</a>.
</p><p>For example, if the directive
</p><pre class="programlisting">
FEDERATION_DOMAIN "example.com"
</pre><p>
is in effect when directive evaluation begins, the variable
<code class="varname">${Conf::FEDERATION_DOMAIN}</code> will be created and
assigned the value "<code class="literal">example.com</code>".
</p><p>Variables within the <code class="varname">Conf</code>
<a class="ulink" href="dacs.exprs.5.html#variables" target="_top">namespace</a>
can be created as needed within expressions (using the <span class="property">EVAL</span>
directive, for example).
Care should be taken not to unintentionally modify the value of a
<span class="command"><strong>DACS</strong></span> directive, however.
</p><p>A standard set of variables is always instantiated when available:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="varname"><a name="var_apache_home"></a>APACHE_HOME</code>
</span></dt><dd><p>The value of the corresponding build-time
symbol</p></dd><dt><span class="term">
<code class="varname"><a name="var_cgi_suffix"></a>CGI_SUFFIX</code>
</span></dt><dd><p>The file name extension for CGI executables, specified
at build-time
</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_conf"></a>DACS_CONF</code></span></dt><dd><p>The full pathname for this jurisdiction's
<code class="filename">dacs.conf</code> file</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_conf_spec"></a>DACS_CONF_SPEC</code></span></dt><dd><p>The pathname specification template used for
this jurisdiction's <code class="filename">dacs.conf</code> file</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_home"></a>DACS_HOME</code></span></dt><dd><p>The value of the corresponding build-time symbol,
from the path set by the <code class="option">--prefix</code> flag or defaulting to
<span class="directory">/usr/local/dacs</span>
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Important</h3><p>This directory should be writable only by
an administrator.</p></div><p>
</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_cgibindir"></a>DACS_CGIBINDIR</code></span></dt><dd><p>The value of the corresponding build-time
symbol</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_release"></a>DACS_RELEASE</code></span></dt><dd><p>The value of the
the compile-time symbol <span class="property">DACS_VERSION_RELEASE</span>
</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_bindir"></a>DACS_BINDIR</code></span></dt><dd><p>The location of the <span class="command"><strong>DACS</strong></span>
<span class="directory">bin</span> directory
</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_sbindir"></a>DACS_SBINDIR</code></span></dt><dd><p>The location of the <span class="command"><strong>DACS</strong></span>
<span class="directory">sbin</span> directory
</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_site_conf"></a>DACS_SITE_CONF</code></span></dt><dd><p>The full pathname for this jurisdiction's
<code class="filename">site.conf</code> file</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_site_conf_spec"></a>DACS_SITE_CONF_SPEC</code></span></dt><dd><p>The pathname specification template used for this
jurisdiction's <code class="filename">site.conf</code> file, if any</p></dd><dt><span class="term">
<code class="varname"><a name="var_dacs_version"></a>DACS_VERSION</code></span></dt><dd><p>The value of
the compile-time symbol <span class="property">DACS_VERSION_NUMBER</span>
</p></dd><dt><span class="term">
<code class="varname"><a name="var_document_root"></a>DOCUMENT_ROOT</code></span></dt><dd><p><span class="command"><strong>Apache</strong></span>'s <code class="envar">DOCUMENT_ROOT</code>
environment variable</p></dd><dt><span class="term">
<code class="varname"><a name="var_exe_suffix"></a>EXE_SUFFIX</code></span></dt><dd><p>The file name extension for non-CGI executables
</p></dd><dt><span class="term">
<code class="varname"><a name="var_federations_root"></a>FEDERATIONS_ROOT</code></span></dt><dd><p>The value of the corresponding build-time
symbol</p></dd><dt><span class="term">
<code class="varname"><a name="var_http_host"></a>HTTP_HOST</code></span></dt><dd><p><span class="command"><strong>Apache</strong></span>'s <code class="envar">HTTP_HOST</code>
environment variable, obtained from the HTTP <code class="literal">Host</code>
request header</p></dd><dt><span class="term">
<code class="varname"><a name="var_jurisdiction_uri"></a>JURISDICTION_URI</code></span></dt><dd><p>The initial part of the request URI,
including scheme and port number, that uniquely identifies the
jurisdiction receiving the service request (also see
<code class="varname">JURISDICTION_URI_PREFIX</code>)</p></dd><dt><span class="term">
<code class="varname"><a name="var_jurisdiction_uri_prefix"></a>JURISDICTION_URI_PREFIX</code></span></dt><dd><p>The URI prefix that uniquely identifies the
jurisdiction receiving the service request (also see
<code class="varname">JURISDICTION_URI</code>)</p></dd><dt><span class="term">
<code class="varname"><a name="var_openssl_prog"></a>OPENSSL_PROG</code></span></dt><dd><p>The full pathname of the <span class="command"><strong>openssl</strong></span>
command, if available</p></dd><dt><span class="term">
<code class="varname"><a name="var_server_addr"></a>SERVER_ADDR</code></span></dt><dd><p><span class="command"><strong>Apache</strong></span>'s <code class="envar">SERVER_ADDR</code>
environment variable</p></dd><dt><span class="term">
<code class="varname"><a name="var_server_name"></a>SERVER_NAME</code></span></dt><dd><p><span class="command"><strong>Apache</strong></span>'s <code class="envar">SERVER_NAME</code>
environment variable</p></dd><dt><span class="term">
<code class="varname"><a name="var_server_port"></a>SERVER_PORT</code></span></dt><dd><p><span class="command"><strong>Apache</strong></span>'s <code class="envar">SERVER_PORT</code>
environment variable</p></dd><dt><span class="term">
<code class="varname"><a name="var_uri_scheme"></a>URI_SCHEME</code></span></dt><dd><p>Set to <code class="literal">https</code> if the service request
came over SSL/TLS (<code class="envar">HTTPS</code> == "<code class="literal">on</code>"),
otherwise <code class="literal">http</code></p></dd></dl></div></div><div class="refsect3"><a name="idm4498"></a><h4>Authentication and Roles</h4><p>This section unfortunately left blank.
</p></div></div></div><div class="refsect1"><a name="idm4501"></a><h2>SEE ALSO</h2><p><a class="ulink" href="dacsconf.1.html" target="_top">dacsconf(1)</a>,
<a class="ulink" href="dacs_conf.8.html" target="_top">dacs_conf(8)</a>,
<a class="ulink" href="dacs.exprs.5.html" target="_top">dacs.exprs(5)</a>
</p></div><div class="refsect1"><a name="idm4507"></a><h2>BUGS</h2><p>There's no way to turn off inherited defaults in a jurisdiction section
or <code class="literal">Default</code> section; i.e., one cannot turn off all
<span class="property">Auth</span> or handler directives
for just one jurisdiction section.
</p></div><div class="refsect1"><a name="idm4512"></a><h2>AUTHOR</h2><p>Distributed Systems Software
(<a class="ulink" href="http://www.dss.ca" target="_top">http://www.dss.ca</a>)
</p></div><div class="refsect1"><a name="idm4516"></a><h2>COPYING</h2><p>Copyright 2003-2016 Distributed Systems Software.
See the
<a class="ulink" href="../misc/LICENSE" target="_top"><code class="filename">LICENSE</code></a>
file that accompanies the distribution
for licensing information.
</p></div>
<!-- Generated from $Id: dacs.conf.5.xml 2933 2016-11-23 18:54:34Z brachman $ -->
<table width="100%"><tr>
<td align="left">
<b>DACS Version 1.4.38a</b></td>
<td align="center">
<b> 2-Jun-2017</b></td>
<td align="right">
<b>DACS.CONF(5)</b></td>
</tr></table>
<hr><p>
<!-- Begin font size selector -->
<table width="100%"><tr><td align="left">
<span class="set_font"><a href="index.html" title="Table of Contents">Table of Contents</a></span></td>
<td align="center"><span class="logo"><a href="http://www.dss.ca"><img src="/css/images/dss-long-14y.png" title="Distributed Systems Software, Inc."></a></span></td>
<td width="5%" align="right">
<div class="fontsize_label" title="Font size selector">Font:</div>
</td>
<td width="10%" align="left">
<!-- NB: must set both left margin and padding to work in all browsers-->
<!-- The onFocus code eliminates annoying post-click decoration -->
<ul id="fontsizecontainer" class="size02">
<li><a href="javascript:setFont('0');" onFocus="if(this.blur)this.blur()" title="Smallest text size [0]"><span>Z</span></a></li>
<li><a href="javascript:setFont('1');" onFocus="if(this.blur)this.blur()" title="Medium text size [1]"><span>Z</span></a></li>
<li><a href="JavaScript:setFont('2');" onFocus="if(this.blur)this.blur()" title="Large text size [2]"><span>Z</span></a></li>
<li><a href="JavaScript:setFont('3');" onFocus="if(this.blur)this.blur()" title="Largest text size [3]"><span>Z</span></a></li>
</ul>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('-');" onFocus="if(this.blur)this.blur()" title="Decrease current font size">−−</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFontConfig();" onFocus="if(this.blur)this.blur()" title="Remember current font size">Set</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('+');" onFocus="if(this.blur)this.blur()" title="Increase current font size">++</a></span>
</td></tr></table>
<!-- End font size selector -->
<script language="javascript" type="text/javascript">
doFontConfig();</script>
</p><small><p><b> $Id: dacs.conf.5.xml 2933 2016-11-23 18:54:34Z brachman $</b></p></small>
</div></body></html>
|