git.sur5r.net Git - openldap/blob - doc/man/man5/slapo-valsort.5

   1 .TH SLAPO-VALSORT 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 2005-2013 The OpenLDAP Foundation All Rights Reserved.
   3 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   4 .\" $OpenLDAP$
   5 .SH NAME
   6 slapo\-valsort \- Value Sorting overlay to slapd
   7 .SH SYNOPSIS
   8 ETCDIR/slapd.conf
   9 .SH DESCRIPTION
  10 The Value Sorting overlay can be used with a backend database to sort the
  11 values of specific multi-valued attributes within a subtree. The sorting
  12 occurs whenever the attributes are returned in a search response.
  13 .LP
  14 Sorting can be specified in ascending or descending order, using either
  15 numeric or alphanumeric sort methods. Additionally, a "weighted" sort can
  16 be specified, which uses a numeric weight prepended to the attribute values.
  17 The weighted sort is always performed in ascending order, but may be combined
  18 with the other methods for values that all have equal weights. The weight
  19 is specified by prepending an integer weight {<\fIweight\fP>}
  20 in front of each value of the attribute for which weighted sorting is
  21 desired. This weighting factor is stripped off and not returned in search
  22 results unless the valsort control is specified (1.3.6.1.4.1.4203.666.5.14).
  23
  24 The valsort control requires a value consisting of a Sequence that contains
  25 a boolean flag. The weighting factor is only returned if the boolean value is TRUE. In
  26 .BR lber-encode (3)
  27 format, the required value must conform to "{b}" syntax.
  28
  29 .SH CONFIGURATION
  30 These
  31 .I slapd.conf
  32 options apply to the Value Sorting overlay.
  33 They should appear after the
  34 .B overlay
  35 directive.
  36 .TP
  37 valsort\-attr <\fIattribute\fP> <\fIbaseDN\fP> (<\fIsort-method\fP> | weighted [<\fIsort-method\fP>])
  38 Configure a sorting method for the specified
  39 .I attribute
  40 in the subtree rooted at
  41 .IR baseDN .
  42 The
  43 .I sort-method
  44 may be one of
  45 .BR alpha\-ascend ,
  46 .BR alpha\-descend ,
  47 .BR numeric\-ascend ,
  48 or
  49 .BR numeric\-descend .
  50 If the special
  51 .B weighted
  52 method is specified, a secondary
  53 .I sort-method
  54 may also be specified. It is an
  55 error to specify an alphanumeric
  56 .I sort-method
  57 for an attribute with Integer
  58 or NumericString syntax, and it is an error to specify a numeric
  59 .I sort-method
  60 for an attribute with a syntax other than Integer or NumericString.
  61 .SH EXAMPLES
  62 .LP
  63 .nf
  64         database mdb
  65         suffix dc=example,dc=com
  66         ...
  67         overlay valsort
  68         valsort\-attr member ou=groups,dc=example,dc=com alpha\-ascend
  69 .fi
  70
  71 To invoke
  72 .BR ldapsearch (1)
  73 with the valsort control, the control value must be set appropriately.
  74 The following octets represent the desired "{b}" encoding:
  75 .LP
  76 .nf
  77         0x30 0x03 0x01 0x01 0xff
  78 .fi
  79
  80 The control can be sent from the command-line using the base64
  81 encoding of the value:
  82 .LP
  83 .nf
  84         ldapsearch -E 1.3.6.1.4.1.4203.666.5.14=::MAMBAf8=
  85 .fi
  86
  87 .SH FILES
  88 .TP
  89 \fIETCDIR/slapd.conf\fP
  90 default \fBslapd\fP configuration file
  91 .SH SEE ALSO
  92 .BR slapd.conf (5),
  93 .BR slapd\-config (5).
  94 .SH ACKNOWLEDGEMENTS
  95 .P
  96 This module was written in 2005 by Howard Chu of Symas Corporation. The
  97 work was sponsored by Stanford University.