← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/createuser.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/createuser.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/createuser.sgml,v 1.39 2003-11-29 19:51:38 pgsql Exp $
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="APP-CREATEUSER">
 
7
 <refmeta>
 
8
  <refentrytitle id="APP-CREATEUSER-TITLE"><application>createuser</application></refentrytitle>
 
9
  <manvolnum>1</manvolnum>
 
10
  <refmiscinfo>Application</refmiscinfo>
 
11
 </refmeta>
 
12
 
 
13
 <refnamediv>
 
14
  <refname>createuser</refname>
 
15
  <refpurpose>define a new <productname>PostgreSQL</productname> user account</refpurpose>
 
16
 </refnamediv>
 
17
 
 
18
 <indexterm zone="app-createuser">
 
19
  <primary>createuser</primary>
 
20
 </indexterm>
 
21
 
 
22
 <refsynopsisdiv>
 
23
  <cmdsynopsis>
 
24
   <command>createuser</command>
 
25
   <arg rep="repeat"><replaceable>option</replaceable></arg>
 
26
   <arg><replaceable>username</replaceable></arg>
 
27
  </cmdsynopsis>
 
28
 </refsynopsisdiv>
 
29
  
 
30
 
 
31
 <refsect1>
 
32
  <title>Description</title>
 
33
  <para>
 
34
   <application>createuser</application> creates a 
 
35
   new <productname>PostgreSQL</productname> user.  
 
36
   Only superusers (users with <literal>usesuper</literal> set in
 
37
   the <literal>pg_shadow</literal> table) can create 
 
38
   new <productname>PostgreSQL</productname> users,
 
39
   so <application>createuser</application> must be
 
40
   invoked by someone who can connect as a <productname>PostgreSQL</productname>
 
41
   superuser.
 
42
  </para>
 
43
 
 
44
  <para>
 
45
   Being a superuser also implies the ability to bypass access permission
 
46
   checks within the database, so superuserdom should not be granted lightly.
 
47
  </para>
 
48
 
 
49
  <para>
 
50
   <application>createuser</application> is a wrapper around the
 
51
   <acronym>SQL</acronym> command <xref linkend="SQL-CREATEUSER"
 
52
   endterm="SQL-CREATEUSER-title">.
 
53
   There is no effective difference between creating users via
 
54
   this utility and via other methods for accessing the server.
 
55
  </para>
 
56
 
 
57
 </refsect1>
 
58
 
 
59
 
 
60
 <refsect1>
 
61
  <title>Options</title>
 
62
 
 
63
  <para>
 
64
   <application>createuser</> accepts the following command-line arguments:
 
65
 
 
66
    <variablelist>
 
67
     <varlistentry>
 
68
      <term><replaceable class="parameter">username</replaceable></term>
 
69
      <listitem>
 
70
       <para>
 
71
        Specifies the name of the <productname>PostgreSQL</productname> user to be created. 
 
72
        This name must be unique among all <productname>PostgreSQL</productname> users.
 
73
       </para>
 
74
      </listitem>
 
75
     </varlistentry>  
 
76
 
 
77
     <varlistentry>
 
78
      <term><option>-a</></term>
 
79
      <term><option>--adduser</></term>
 
80
      <listitem>
 
81
       <para>
 
82
        The new user is allowed to create other users.
 
83
        (Note: Actually, this makes the new user a <emphasis>superuser</>.
 
84
        The option is poorly named.)
 
85
       </para>
 
86
      </listitem>
 
87
     </varlistentry>
 
88
 
 
89
     <varlistentry>
 
90
      <term><option>-A</></term>
 
91
      <term><option>--no-adduser</></term>
 
92
      <listitem>
 
93
       <para>
 
94
        The new user is not allowed to create other users (i.e.,
 
95
        the new user is a regular user, not a superuser).
 
96
        This is the default.
 
97
       </para>
 
98
      </listitem>
 
99
     </varlistentry>
 
100
 
 
101
     <varlistentry>
 
102
      <term><option>-d</></term>
 
103
      <term><option>--createdb</></term>
 
104
      <listitem>
 
105
       <para>
 
106
        The new user is allowed to create databases.
 
107
       </para>
 
108
      </listitem>
 
109
     </varlistentry>
 
110
 
 
111
     <varlistentry>
 
112
      <term><option>-D</></term>
 
113
      <term><option>--no-createdb</></term>
 
114
      <listitem>
 
115
       <para>
 
116
        The new user is not allowed to create databases.
 
117
        This is the default.
 
118
       </para>
 
119
      </listitem>
 
120
     </varlistentry>
 
121
 
 
122
     <varlistentry>
 
123
      <term><option>-e</></term>
 
124
      <term><option>--echo</></term>
 
125
      <listitem>
 
126
       <para>
 
127
        Echo the commands that <application>createuser</application> generates
 
128
        and sends to the server.
 
129
       </para>
 
130
      </listitem>
 
131
     </varlistentry>
 
132
 
 
133
     <varlistentry>
 
134
      <term><option>-E</></term>
 
135
      <term><option>--encrypted</></term>
 
136
      <listitem>
 
137
       <para>
 
138
        Encrypts the user's password stored in the database. If not
 
139
        specified, the default password behavior is used.
 
140
       </para>
 
141
      </listitem>
 
142
     </varlistentry>
 
143
 
 
144
     <varlistentry>
 
145
      <term><option>-i <replaceable class="parameter">number</replaceable></></term>
 
146
      <term><option>--sysid <replaceable class="parameter">number</replaceable></></term>
 
147
      <listitem>
 
148
       <para>
 
149
       Allows you to pick a non-default user ID for the new user. This is not
 
150
       necessary, but some people like it.
 
151
       </para>
 
152
      </listitem>
 
153
     </varlistentry>
 
154
 
 
155
     <varlistentry>
 
156
      <term><option>-N</></term>
 
157
      <term><option>--unencrypted</></term>
 
158
      <listitem>
 
159
       <para>
 
160
        Does not encrypt the user's password stored in the database. If
 
161
        not specified, the default password behavior is used.
 
162
       </para>
 
163
      </listitem>
 
164
     </varlistentry>
 
165
 
 
166
     <varlistentry>
 
167
      <term><option>-P</></term>
 
168
      <term><option>--pwprompt</></term>
 
169
      <listitem>
 
170
       <para>
 
171
       If given, <application>createuser</application> will issue a prompt for
 
172
       the password of the new user. This is not necessary if you do not plan
 
173
       on using password authentication.
 
174
       </para>
 
175
      </listitem>
 
176
     </varlistentry>
 
177
 
 
178
     <varlistentry>
 
179
      <term><option>-q</></term>
 
180
      <term><option>--quiet</></term>
 
181
      <listitem>
 
182
       <para>
 
183
        Do not display a response.
 
184
       </para>
 
185
      </listitem>
 
186
     </varlistentry>
 
187
    </variablelist>
 
188
  </para>
 
189
 
 
190
  <para>
 
191
   You will be prompted for a name and other missing information if it
 
192
   is not specified on the command line.
 
193
  </para>
 
194
 
 
195
  <para>
 
196
   <application>createuser</application> also accepts the following
 
197
   command-line arguments for connection parameters:
 
198
    
 
199
   <variablelist>
 
200
     <varlistentry>
 
201
      <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 
202
      <term><option>--host <replaceable class="parameter">host</replaceable></></term>
 
203
      <listitem>
 
204
       <para>
 
205
        Specifies the host name of the machine on which the 
 
206
        server
 
207
        is running.  If the value begins with a slash, it is used 
 
208
        as the directory for the Unix domain socket.
 
209
       </para>
 
210
      </listitem>
 
211
     </varlistentry>
 
212
 
 
213
     <varlistentry>
 
214
      <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 
215
      <term><option>--port <replaceable class="parameter">port</replaceable></></term>
 
216
      <listitem>
 
217
       <para>
 
218
        Specifies the TCP port or local Unix domain socket file 
 
219
        extension on which the server
 
220
        is listening for connections.
 
221
       </para>
 
222
      </listitem>
 
223
     </varlistentry>
 
224
 
 
225
     <varlistentry>
 
226
      <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 
227
      <term><option>--username <replaceable class="parameter">username</replaceable></></term>
 
228
      <listitem>
 
229
       <para>
 
230
        User name to connect as (not the user name to create).
 
231
       </para>
 
232
      </listitem>
 
233
     </varlistentry>
 
234
 
 
235
     <varlistentry>
 
236
      <term><option>-W</></term>
 
237
      <term><option>--password</></term>
 
238
      <listitem>
 
239
       <para>
 
240
        Force password prompt (to connect to the server, not for the
 
241
        password of the new user).
 
242
       </para>
 
243
      </listitem>
 
244
     </varlistentry>
 
245
   </variablelist>
 
246
  </para>
 
247
 </refsect1>
 
248
 
 
249
 
 
250
 <refsect1>
 
251
  <title>Environment</title>
 
252
 
 
253
  <variablelist>
 
254
   <varlistentry>
 
255
    <term><envar>PGHOST</envar></term>
 
256
    <term><envar>PGPORT</envar></term>
 
257
    <term><envar>PGUSER</envar></term>
 
258
 
 
259
    <listitem>
 
260
     <para>
 
261
      Default connection parameters
 
262
     </para>
 
263
    </listitem>
 
264
   </varlistentry>
 
265
  </variablelist>
 
266
 </refsect1>
 
267
 
 
268
 
 
269
 <refsect1>
 
270
  <title>Diagnostics</title>
 
271
 
 
272
  <para>
 
273
   In case of difficulty, see <xref linkend="SQL-CREATEUSER"
 
274
   endterm="sql-createuser-title"> and <xref linkend="APP-PSQL"> for
 
275
   discussions of potential problems and error messages.
 
276
   The database server must be running at the
 
277
   targeted host.  Also, any default connection settings and environment
 
278
   variables used by the <application>libpq</application> front-end
 
279
   library will apply.
 
280
  </para>
 
281
 
 
282
 </refsect1>
 
283
 
 
284
 
 
285
 <refsect1>
 
286
  <title>Examples</title>
 
287
 
 
288
   <para>
 
289
    To create a user <literal>joe</literal> on the default database
 
290
    server:
 
291
<screen>
 
292
<prompt>$ </prompt><userinput>createuser joe</userinput>
 
293
<computeroutput>Is the new user allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
 
294
<computeroutput>Shall the new user be allowed to create more new users? (y/n) </computeroutput><userinput>n</userinput>
 
295
<computeroutput>CREATE USER</computeroutput>
 
296
</screen>
 
297
   </para>
 
298
 
 
299
   <para>
 
300
    To create the same user <literal>joe</literal> using the
 
301
    server on host <literal>eden</>, port 5000, avoiding the prompts and
 
302
    taking a look at the underlying command:
 
303
<screen>
 
304
<prompt>$ </prompt><userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
 
305
<computeroutput>CREATE USER "joe" NOCREATEDB NOCREATEUSER</computeroutput>
 
306
<computeroutput>CREATE USER</computeroutput>
 
307
</screen>
 
308
   </para>
 
309
 </refsect1>
 
310
 
 
311
 
 
312
 <refsect1>
 
313
  <title>See Also</title>
 
314
 
 
315
  <simplelist type="inline">
 
316
   <member><xref linkend="app-dropuser"></member>
 
317
   <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
 
318
  </simplelist>
 
319
 </refsect1>
 
320
 
 
321
</refentry>
 
322
 
 
323
<!-- Keep this comment at the end of the file
 
324
Local variables:
 
325
mode: sgml
 
326
sgml-omittag:nil
 
327
sgml-shorttag:t
 
328
sgml-minimize-attributes:nil
 
329
sgml-always-quote-attributes:t
 
330
sgml-indent-step:1
 
331
sgml-indent-data:t
 
332
sgml-parent-document:nil
 
333
sgml-default-dtd-file:"../reference.ced"
 
334
sgml-exposed-tags:nil
 
335
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
336
sgml-local-ecat-files:nil
 
337
End:
 
338
-->