1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/trunk/AUTHORS Tue Jan 20 10:21:03 2009 +0100
1.3 @@ -0,0 +1,26 @@
1.4 +AUTHORS & CREDITS
1.5 +=================
1.6 +
1.7 +As most software applications "StarOffice News Server" is based on the work
1.8 +of individuals or projects. These fine people contributing to the OpenSource
1.9 +community are mentioned here:
1.10 +
1.11 +StarOffice News Server
1.12 +----------------------
1.13 +(c)Copyright 2009 by
1.14 + * Sun Microsystems, Inc.
1.15 + * Christian Lins <christian.lins@sun.com>
1.16 +
1.17 +based partly upon
1.18 +
1.19 +Neat NNTP Daemon (n3tpd)
1.20 +------------------------
1.21 +(c)Copyright 2007, 2008 by Christian Lins <christian.lins@web.de>
1.22 +
1.23 +based partly upon
1.24 +
1.25 +tnntpd
1.26 +------
1.27 +(c)Copyright 2003 by Dennis Schwerdel
1.28 +
1.29 +If you find someone missing here, please contact the project leader!
1.30 \ No newline at end of file
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/trunk/COPYING Tue Jan 20 10:21:03 2009 +0100
2.3 @@ -0,0 +1,674 @@
2.4 + GNU GENERAL PUBLIC LICENSE
2.5 + Version 3, 29 June 2007
2.6 +
2.7 + Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
2.8 + Everyone is permitted to copy and distribute verbatim copies
2.9 + of this license document, but changing it is not allowed.
2.10 +
2.11 + Preamble
2.12 +
2.13 + The GNU General Public License is a free, copyleft license for
2.14 +software and other kinds of works.
2.15 +
2.16 + The licenses for most software and other practical works are designed
2.17 +to take away your freedom to share and change the works. By contrast,
2.18 +the GNU General Public License is intended to guarantee your freedom to
2.19 +share and change all versions of a program--to make sure it remains free
2.20 +software for all its users. We, the Free Software Foundation, use the
2.21 +GNU General Public License for most of our software; it applies also to
2.22 +any other work released this way by its authors. You can apply it to
2.23 +your programs, too.
2.24 +
2.25 + When we speak of free software, we are referring to freedom, not
2.26 +price. Our General Public Licenses are designed to make sure that you
2.27 +have the freedom to distribute copies of free software (and charge for
2.28 +them if you wish), that you receive source code or can get it if you
2.29 +want it, that you can change the software or use pieces of it in new
2.30 +free programs, and that you know you can do these things.
2.31 +
2.32 + To protect your rights, we need to prevent others from denying you
2.33 +these rights or asking you to surrender the rights. Therefore, you have
2.34 +certain responsibilities if you distribute copies of the software, or if
2.35 +you modify it: responsibilities to respect the freedom of others.
2.36 +
2.37 + For example, if you distribute copies of such a program, whether
2.38 +gratis or for a fee, you must pass on to the recipients the same
2.39 +freedoms that you received. You must make sure that they, too, receive
2.40 +or can get the source code. And you must show them these terms so they
2.41 +know their rights.
2.42 +
2.43 + Developers that use the GNU GPL protect your rights with two steps:
2.44 +(1) assert copyright on the software, and (2) offer you this License
2.45 +giving you legal permission to copy, distribute and/or modify it.
2.46 +
2.47 + For the developers' and authors' protection, the GPL clearly explains
2.48 +that there is no warranty for this free software. For both users' and
2.49 +authors' sake, the GPL requires that modified versions be marked as
2.50 +changed, so that their problems will not be attributed erroneously to
2.51 +authors of previous versions.
2.52 +
2.53 + Some devices are designed to deny users access to install or run
2.54 +modified versions of the software inside them, although the manufacturer
2.55 +can do so. This is fundamentally incompatible with the aim of
2.56 +protecting users' freedom to change the software. The systematic
2.57 +pattern of such abuse occurs in the area of products for individuals to
2.58 +use, which is precisely where it is most unacceptable. Therefore, we
2.59 +have designed this version of the GPL to prohibit the practice for those
2.60 +products. If such problems arise substantially in other domains, we
2.61 +stand ready to extend this provision to those domains in future versions
2.62 +of the GPL, as needed to protect the freedom of users.
2.63 +
2.64 + Finally, every program is threatened constantly by software patents.
2.65 +States should not allow patents to restrict development and use of
2.66 +software on general-purpose computers, but in those that do, we wish to
2.67 +avoid the special danger that patents applied to a free program could
2.68 +make it effectively proprietary. To prevent this, the GPL assures that
2.69 +patents cannot be used to render the program non-free.
2.70 +
2.71 + The precise terms and conditions for copying, distribution and
2.72 +modification follow.
2.73 +
2.74 + TERMS AND CONDITIONS
2.75 +
2.76 + 0. Definitions.
2.77 +
2.78 + "This License" refers to version 3 of the GNU General Public License.
2.79 +
2.80 + "Copyright" also means copyright-like laws that apply to other kinds of
2.81 +works, such as semiconductor masks.
2.82 +
2.83 + "The Program" refers to any copyrightable work licensed under this
2.84 +License. Each licensee is addressed as "you". "Licensees" and
2.85 +"recipients" may be individuals or organizations.
2.86 +
2.87 + To "modify" a work means to copy from or adapt all or part of the work
2.88 +in a fashion requiring copyright permission, other than the making of an
2.89 +exact copy. The resulting work is called a "modified version" of the
2.90 +earlier work or a work "based on" the earlier work.
2.91 +
2.92 + A "covered work" means either the unmodified Program or a work based
2.93 +on the Program.
2.94 +
2.95 + To "propagate" a work means to do anything with it that, without
2.96 +permission, would make you directly or secondarily liable for
2.97 +infringement under applicable copyright law, except executing it on a
2.98 +computer or modifying a private copy. Propagation includes copying,
2.99 +distribution (with or without modification), making available to the
2.100 +public, and in some countries other activities as well.
2.101 +
2.102 + To "convey" a work means any kind of propagation that enables other
2.103 +parties to make or receive copies. Mere interaction with a user through
2.104 +a computer network, with no transfer of a copy, is not conveying.
2.105 +
2.106 + An interactive user interface displays "Appropriate Legal Notices"
2.107 +to the extent that it includes a convenient and prominently visible
2.108 +feature that (1) displays an appropriate copyright notice, and (2)
2.109 +tells the user that there is no warranty for the work (except to the
2.110 +extent that warranties are provided), that licensees may convey the
2.111 +work under this License, and how to view a copy of this License. If
2.112 +the interface presents a list of user commands or options, such as a
2.113 +menu, a prominent item in the list meets this criterion.
2.114 +
2.115 + 1. Source Code.
2.116 +
2.117 + The "source code" for a work means the preferred form of the work
2.118 +for making modifications to it. "Object code" means any non-source
2.119 +form of a work.
2.120 +
2.121 + A "Standard Interface" means an interface that either is an official
2.122 +standard defined by a recognized standards body, or, in the case of
2.123 +interfaces specified for a particular programming language, one that
2.124 +is widely used among developers working in that language.
2.125 +
2.126 + The "System Libraries" of an executable work include anything, other
2.127 +than the work as a whole, that (a) is included in the normal form of
2.128 +packaging a Major Component, but which is not part of that Major
2.129 +Component, and (b) serves only to enable use of the work with that
2.130 +Major Component, or to implement a Standard Interface for which an
2.131 +implementation is available to the public in source code form. A
2.132 +"Major Component", in this context, means a major essential component
2.133 +(kernel, window system, and so on) of the specific operating system
2.134 +(if any) on which the executable work runs, or a compiler used to
2.135 +produce the work, or an object code interpreter used to run it.
2.136 +
2.137 + The "Corresponding Source" for a work in object code form means all
2.138 +the source code needed to generate, install, and (for an executable
2.139 +work) run the object code and to modify the work, including scripts to
2.140 +control those activities. However, it does not include the work's
2.141 +System Libraries, or general-purpose tools or generally available free
2.142 +programs which are used unmodified in performing those activities but
2.143 +which are not part of the work. For example, Corresponding Source
2.144 +includes interface definition files associated with source files for
2.145 +the work, and the source code for shared libraries and dynamically
2.146 +linked subprograms that the work is specifically designed to require,
2.147 +such as by intimate data communication or control flow between those
2.148 +subprograms and other parts of the work.
2.149 +
2.150 + The Corresponding Source need not include anything that users
2.151 +can regenerate automatically from other parts of the Corresponding
2.152 +Source.
2.153 +
2.154 + The Corresponding Source for a work in source code form is that
2.155 +same work.
2.156 +
2.157 + 2. Basic Permissions.
2.158 +
2.159 + All rights granted under this License are granted for the term of
2.160 +copyright on the Program, and are irrevocable provided the stated
2.161 +conditions are met. This License explicitly affirms your unlimited
2.162 +permission to run the unmodified Program. The output from running a
2.163 +covered work is covered by this License only if the output, given its
2.164 +content, constitutes a covered work. This License acknowledges your
2.165 +rights of fair use or other equivalent, as provided by copyright law.
2.166 +
2.167 + You may make, run and propagate covered works that you do not
2.168 +convey, without conditions so long as your license otherwise remains
2.169 +in force. You may convey covered works to others for the sole purpose
2.170 +of having them make modifications exclusively for you, or provide you
2.171 +with facilities for running those works, provided that you comply with
2.172 +the terms of this License in conveying all material for which you do
2.173 +not control copyright. Those thus making or running the covered works
2.174 +for you must do so exclusively on your behalf, under your direction
2.175 +and control, on terms that prohibit them from making any copies of
2.176 +your copyrighted material outside their relationship with you.
2.177 +
2.178 + Conveying under any other circumstances is permitted solely under
2.179 +the conditions stated below. Sublicensing is not allowed; section 10
2.180 +makes it unnecessary.
2.181 +
2.182 + 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
2.183 +
2.184 + No covered work shall be deemed part of an effective technological
2.185 +measure under any applicable law fulfilling obligations under article
2.186 +11 of the WIPO copyright treaty adopted on 20 December 1996, or
2.187 +similar laws prohibiting or restricting circumvention of such
2.188 +measures.
2.189 +
2.190 + When you convey a covered work, you waive any legal power to forbid
2.191 +circumvention of technological measures to the extent such circumvention
2.192 +is effected by exercising rights under this License with respect to
2.193 +the covered work, and you disclaim any intention to limit operation or
2.194 +modification of the work as a means of enforcing, against the work's
2.195 +users, your or third parties' legal rights to forbid circumvention of
2.196 +technological measures.
2.197 +
2.198 + 4. Conveying Verbatim Copies.
2.199 +
2.200 + You may convey verbatim copies of the Program's source code as you
2.201 +receive it, in any medium, provided that you conspicuously and
2.202 +appropriately publish on each copy an appropriate copyright notice;
2.203 +keep intact all notices stating that this License and any
2.204 +non-permissive terms added in accord with section 7 apply to the code;
2.205 +keep intact all notices of the absence of any warranty; and give all
2.206 +recipients a copy of this License along with the Program.
2.207 +
2.208 + You may charge any price or no price for each copy that you convey,
2.209 +and you may offer support or warranty protection for a fee.
2.210 +
2.211 + 5. Conveying Modified Source Versions.
2.212 +
2.213 + You may convey a work based on the Program, or the modifications to
2.214 +produce it from the Program, in the form of source code under the
2.215 +terms of section 4, provided that you also meet all of these conditions:
2.216 +
2.217 + a) The work must carry prominent notices stating that you modified
2.218 + it, and giving a relevant date.
2.219 +
2.220 + b) The work must carry prominent notices stating that it is
2.221 + released under this License and any conditions added under section
2.222 + 7. This requirement modifies the requirement in section 4 to
2.223 + "keep intact all notices".
2.224 +
2.225 + c) You must license the entire work, as a whole, under this
2.226 + License to anyone who comes into possession of a copy. This
2.227 + License will therefore apply, along with any applicable section 7
2.228 + additional terms, to the whole of the work, and all its parts,
2.229 + regardless of how they are packaged. This License gives no
2.230 + permission to license the work in any other way, but it does not
2.231 + invalidate such permission if you have separately received it.
2.232 +
2.233 + d) If the work has interactive user interfaces, each must display
2.234 + Appropriate Legal Notices; however, if the Program has interactive
2.235 + interfaces that do not display Appropriate Legal Notices, your
2.236 + work need not make them do so.
2.237 +
2.238 + A compilation of a covered work with other separate and independent
2.239 +works, which are not by their nature extensions of the covered work,
2.240 +and which are not combined with it such as to form a larger program,
2.241 +in or on a volume of a storage or distribution medium, is called an
2.242 +"aggregate" if the compilation and its resulting copyright are not
2.243 +used to limit the access or legal rights of the compilation's users
2.244 +beyond what the individual works permit. Inclusion of a covered work
2.245 +in an aggregate does not cause this License to apply to the other
2.246 +parts of the aggregate.
2.247 +
2.248 + 6. Conveying Non-Source Forms.
2.249 +
2.250 + You may convey a covered work in object code form under the terms
2.251 +of sections 4 and 5, provided that you also convey the
2.252 +machine-readable Corresponding Source under the terms of this License,
2.253 +in one of these ways:
2.254 +
2.255 + a) Convey the object code in, or embodied in, a physical product
2.256 + (including a physical distribution medium), accompanied by the
2.257 + Corresponding Source fixed on a durable physical medium
2.258 + customarily used for software interchange.
2.259 +
2.260 + b) Convey the object code in, or embodied in, a physical product
2.261 + (including a physical distribution medium), accompanied by a
2.262 + written offer, valid for at least three years and valid for as
2.263 + long as you offer spare parts or customer support for that product
2.264 + model, to give anyone who possesses the object code either (1) a
2.265 + copy of the Corresponding Source for all the software in the
2.266 + product that is covered by this License, on a durable physical
2.267 + medium customarily used for software interchange, for a price no
2.268 + more than your reasonable cost of physically performing this
2.269 + conveying of source, or (2) access to copy the
2.270 + Corresponding Source from a network server at no charge.
2.271 +
2.272 + c) Convey individual copies of the object code with a copy of the
2.273 + written offer to provide the Corresponding Source. This
2.274 + alternative is allowed only occasionally and noncommercially, and
2.275 + only if you received the object code with such an offer, in accord
2.276 + with subsection 6b.
2.277 +
2.278 + d) Convey the object code by offering access from a designated
2.279 + place (gratis or for a charge), and offer equivalent access to the
2.280 + Corresponding Source in the same way through the same place at no
2.281 + further charge. You need not require recipients to copy the
2.282 + Corresponding Source along with the object code. If the place to
2.283 + copy the object code is a network server, the Corresponding Source
2.284 + may be on a different server (operated by you or a third party)
2.285 + that supports equivalent copying facilities, provided you maintain
2.286 + clear directions next to the object code saying where to find the
2.287 + Corresponding Source. Regardless of what server hosts the
2.288 + Corresponding Source, you remain obligated to ensure that it is
2.289 + available for as long as needed to satisfy these requirements.
2.290 +
2.291 + e) Convey the object code using peer-to-peer transmission, provided
2.292 + you inform other peers where the object code and Corresponding
2.293 + Source of the work are being offered to the general public at no
2.294 + charge under subsection 6d.
2.295 +
2.296 + A separable portion of the object code, whose source code is excluded
2.297 +from the Corresponding Source as a System Library, need not be
2.298 +included in conveying the object code work.
2.299 +
2.300 + A "User Product" is either (1) a "consumer product", which means any
2.301 +tangible personal property which is normally used for personal, family,
2.302 +or household purposes, or (2) anything designed or sold for incorporation
2.303 +into a dwelling. In determining whether a product is a consumer product,
2.304 +doubtful cases shall be resolved in favor of coverage. For a particular
2.305 +product received by a particular user, "normally used" refers to a
2.306 +typical or common use of that class of product, regardless of the status
2.307 +of the particular user or of the way in which the particular user
2.308 +actually uses, or expects or is expected to use, the product. A product
2.309 +is a consumer product regardless of whether the product has substantial
2.310 +commercial, industrial or non-consumer uses, unless such uses represent
2.311 +the only significant mode of use of the product.
2.312 +
2.313 + "Installation Information" for a User Product means any methods,
2.314 +procedures, authorization keys, or other information required to install
2.315 +and execute modified versions of a covered work in that User Product from
2.316 +a modified version of its Corresponding Source. The information must
2.317 +suffice to ensure that the continued functioning of the modified object
2.318 +code is in no case prevented or interfered with solely because
2.319 +modification has been made.
2.320 +
2.321 + If you convey an object code work under this section in, or with, or
2.322 +specifically for use in, a User Product, and the conveying occurs as
2.323 +part of a transaction in which the right of possession and use of the
2.324 +User Product is transferred to the recipient in perpetuity or for a
2.325 +fixed term (regardless of how the transaction is characterized), the
2.326 +Corresponding Source conveyed under this section must be accompanied
2.327 +by the Installation Information. But this requirement does not apply
2.328 +if neither you nor any third party retains the ability to install
2.329 +modified object code on the User Product (for example, the work has
2.330 +been installed in ROM).
2.331 +
2.332 + The requirement to provide Installation Information does not include a
2.333 +requirement to continue to provide support service, warranty, or updates
2.334 +for a work that has been modified or installed by the recipient, or for
2.335 +the User Product in which it has been modified or installed. Access to a
2.336 +network may be denied when the modification itself materially and
2.337 +adversely affects the operation of the network or violates the rules and
2.338 +protocols for communication across the network.
2.339 +
2.340 + Corresponding Source conveyed, and Installation Information provided,
2.341 +in accord with this section must be in a format that is publicly
2.342 +documented (and with an implementation available to the public in
2.343 +source code form), and must require no special password or key for
2.344 +unpacking, reading or copying.
2.345 +
2.346 + 7. Additional Terms.
2.347 +
2.348 + "Additional permissions" are terms that supplement the terms of this
2.349 +License by making exceptions from one or more of its conditions.
2.350 +Additional permissions that are applicable to the entire Program shall
2.351 +be treated as though they were included in this License, to the extent
2.352 +that they are valid under applicable law. If additional permissions
2.353 +apply only to part of the Program, that part may be used separately
2.354 +under those permissions, but the entire Program remains governed by
2.355 +this License without regard to the additional permissions.
2.356 +
2.357 + When you convey a copy of a covered work, you may at your option
2.358 +remove any additional permissions from that copy, or from any part of
2.359 +it. (Additional permissions may be written to require their own
2.360 +removal in certain cases when you modify the work.) You may place
2.361 +additional permissions on material, added by you to a covered work,
2.362 +for which you have or can give appropriate copyright permission.
2.363 +
2.364 + Notwithstanding any other provision of this License, for material you
2.365 +add to a covered work, you may (if authorized by the copyright holders of
2.366 +that material) supplement the terms of this License with terms:
2.367 +
2.368 + a) Disclaiming warranty or limiting liability differently from the
2.369 + terms of sections 15 and 16 of this License; or
2.370 +
2.371 + b) Requiring preservation of specified reasonable legal notices or
2.372 + author attributions in that material or in the Appropriate Legal
2.373 + Notices displayed by works containing it; or
2.374 +
2.375 + c) Prohibiting misrepresentation of the origin of that material, or
2.376 + requiring that modified versions of such material be marked in
2.377 + reasonable ways as different from the original version; or
2.378 +
2.379 + d) Limiting the use for publicity purposes of names of licensors or
2.380 + authors of the material; or
2.381 +
2.382 + e) Declining to grant rights under trademark law for use of some
2.383 + trade names, trademarks, or service marks; or
2.384 +
2.385 + f) Requiring indemnification of licensors and authors of that
2.386 + material by anyone who conveys the material (or modified versions of
2.387 + it) with contractual assumptions of liability to the recipient, for
2.388 + any liability that these contractual assumptions directly impose on
2.389 + those licensors and authors.
2.390 +
2.391 + All other non-permissive additional terms are considered "further
2.392 +restrictions" within the meaning of section 10. If the Program as you
2.393 +received it, or any part of it, contains a notice stating that it is
2.394 +governed by this License along with a term that is a further
2.395 +restriction, you may remove that term. If a license document contains
2.396 +a further restriction but permits relicensing or conveying under this
2.397 +License, you may add to a covered work material governed by the terms
2.398 +of that license document, provided that the further restriction does
2.399 +not survive such relicensing or conveying.
2.400 +
2.401 + If you add terms to a covered work in accord with this section, you
2.402 +must place, in the relevant source files, a statement of the
2.403 +additional terms that apply to those files, or a notice indicating
2.404 +where to find the applicable terms.
2.405 +
2.406 + Additional terms, permissive or non-permissive, may be stated in the
2.407 +form of a separately written license, or stated as exceptions;
2.408 +the above requirements apply either way.
2.409 +
2.410 + 8. Termination.
2.411 +
2.412 + You may not propagate or modify a covered work except as expressly
2.413 +provided under this License. Any attempt otherwise to propagate or
2.414 +modify it is void, and will automatically terminate your rights under
2.415 +this License (including any patent licenses granted under the third
2.416 +paragraph of section 11).
2.417 +
2.418 + However, if you cease all violation of this License, then your
2.419 +license from a particular copyright holder is reinstated (a)
2.420 +provisionally, unless and until the copyright holder explicitly and
2.421 +finally terminates your license, and (b) permanently, if the copyright
2.422 +holder fails to notify you of the violation by some reasonable means
2.423 +prior to 60 days after the cessation.
2.424 +
2.425 + Moreover, your license from a particular copyright holder is
2.426 +reinstated permanently if the copyright holder notifies you of the
2.427 +violation by some reasonable means, this is the first time you have
2.428 +received notice of violation of this License (for any work) from that
2.429 +copyright holder, and you cure the violation prior to 30 days after
2.430 +your receipt of the notice.
2.431 +
2.432 + Termination of your rights under this section does not terminate the
2.433 +licenses of parties who have received copies or rights from you under
2.434 +this License. If your rights have been terminated and not permanently
2.435 +reinstated, you do not qualify to receive new licenses for the same
2.436 +material under section 10.
2.437 +
2.438 + 9. Acceptance Not Required for Having Copies.
2.439 +
2.440 + You are not required to accept this License in order to receive or
2.441 +run a copy of the Program. Ancillary propagation of a covered work
2.442 +occurring solely as a consequence of using peer-to-peer transmission
2.443 +to receive a copy likewise does not require acceptance. However,
2.444 +nothing other than this License grants you permission to propagate or
2.445 +modify any covered work. These actions infringe copyright if you do
2.446 +not accept this License. Therefore, by modifying or propagating a
2.447 +covered work, you indicate your acceptance of this License to do so.
2.448 +
2.449 + 10. Automatic Licensing of Downstream Recipients.
2.450 +
2.451 + Each time you convey a covered work, the recipient automatically
2.452 +receives a license from the original licensors, to run, modify and
2.453 +propagate that work, subject to this License. You are not responsible
2.454 +for enforcing compliance by third parties with this License.
2.455 +
2.456 + An "entity transaction" is a transaction transferring control of an
2.457 +organization, or substantially all assets of one, or subdividing an
2.458 +organization, or merging organizations. If propagation of a covered
2.459 +work results from an entity transaction, each party to that
2.460 +transaction who receives a copy of the work also receives whatever
2.461 +licenses to the work the party's predecessor in interest had or could
2.462 +give under the previous paragraph, plus a right to possession of the
2.463 +Corresponding Source of the work from the predecessor in interest, if
2.464 +the predecessor has it or can get it with reasonable efforts.
2.465 +
2.466 + You may not impose any further restrictions on the exercise of the
2.467 +rights granted or affirmed under this License. For example, you may
2.468 +not impose a license fee, royalty, or other charge for exercise of
2.469 +rights granted under this License, and you may not initiate litigation
2.470 +(including a cross-claim or counterclaim in a lawsuit) alleging that
2.471 +any patent claim is infringed by making, using, selling, offering for
2.472 +sale, or importing the Program or any portion of it.
2.473 +
2.474 + 11. Patents.
2.475 +
2.476 + A "contributor" is a copyright holder who authorizes use under this
2.477 +License of the Program or a work on which the Program is based. The
2.478 +work thus licensed is called the contributor's "contributor version".
2.479 +
2.480 + A contributor's "essential patent claims" are all patent claims
2.481 +owned or controlled by the contributor, whether already acquired or
2.482 +hereafter acquired, that would be infringed by some manner, permitted
2.483 +by this License, of making, using, or selling its contributor version,
2.484 +but do not include claims that would be infringed only as a
2.485 +consequence of further modification of the contributor version. For
2.486 +purposes of this definition, "control" includes the right to grant
2.487 +patent sublicenses in a manner consistent with the requirements of
2.488 +this License.
2.489 +
2.490 + Each contributor grants you a non-exclusive, worldwide, royalty-free
2.491 +patent license under the contributor's essential patent claims, to
2.492 +make, use, sell, offer for sale, import and otherwise run, modify and
2.493 +propagate the contents of its contributor version.
2.494 +
2.495 + In the following three paragraphs, a "patent license" is any express
2.496 +agreement or commitment, however denominated, not to enforce a patent
2.497 +(such as an express permission to practice a patent or covenant not to
2.498 +sue for patent infringement). To "grant" such a patent license to a
2.499 +party means to make such an agreement or commitment not to enforce a
2.500 +patent against the party.
2.501 +
2.502 + If you convey a covered work, knowingly relying on a patent license,
2.503 +and the Corresponding Source of the work is not available for anyone
2.504 +to copy, free of charge and under the terms of this License, through a
2.505 +publicly available network server or other readily accessible means,
2.506 +then you must either (1) cause the Corresponding Source to be so
2.507 +available, or (2) arrange to deprive yourself of the benefit of the
2.508 +patent license for this particular work, or (3) arrange, in a manner
2.509 +consistent with the requirements of this License, to extend the patent
2.510 +license to downstream recipients. "Knowingly relying" means you have
2.511 +actual knowledge that, but for the patent license, your conveying the
2.512 +covered work in a country, or your recipient's use of the covered work
2.513 +in a country, would infringe one or more identifiable patents in that
2.514 +country that you have reason to believe are valid.
2.515 +
2.516 + If, pursuant to or in connection with a single transaction or
2.517 +arrangement, you convey, or propagate by procuring conveyance of, a
2.518 +covered work, and grant a patent license to some of the parties
2.519 +receiving the covered work authorizing them to use, propagate, modify
2.520 +or convey a specific copy of the covered work, then the patent license
2.521 +you grant is automatically extended to all recipients of the covered
2.522 +work and works based on it.
2.523 +
2.524 + A patent license is "discriminatory" if it does not include within
2.525 +the scope of its coverage, prohibits the exercise of, or is
2.526 +conditioned on the non-exercise of one or more of the rights that are
2.527 +specifically granted under this License. You may not convey a covered
2.528 +work if you are a party to an arrangement with a third party that is
2.529 +in the business of distributing software, under which you make payment
2.530 +to the third party based on the extent of your activity of conveying
2.531 +the work, and under which the third party grants, to any of the
2.532 +parties who would receive the covered work from you, a discriminatory
2.533 +patent license (a) in connection with copies of the covered work
2.534 +conveyed by you (or copies made from those copies), or (b) primarily
2.535 +for and in connection with specific products or compilations that
2.536 +contain the covered work, unless you entered into that arrangement,
2.537 +or that patent license was granted, prior to 28 March 2007.
2.538 +
2.539 + Nothing in this License shall be construed as excluding or limiting
2.540 +any implied license or other defenses to infringement that may
2.541 +otherwise be available to you under applicable patent law.
2.542 +
2.543 + 12. No Surrender of Others' Freedom.
2.544 +
2.545 + If conditions are imposed on you (whether by court order, agreement or
2.546 +otherwise) that contradict the conditions of this License, they do not
2.547 +excuse you from the conditions of this License. If you cannot convey a
2.548 +covered work so as to satisfy simultaneously your obligations under this
2.549 +License and any other pertinent obligations, then as a consequence you may
2.550 +not convey it at all. For example, if you agree to terms that obligate you
2.551 +to collect a royalty for further conveying from those to whom you convey
2.552 +the Program, the only way you could satisfy both those terms and this
2.553 +License would be to refrain entirely from conveying the Program.
2.554 +
2.555 + 13. Use with the GNU Affero General Public License.
2.556 +
2.557 + Notwithstanding any other provision of this License, you have
2.558 +permission to link or combine any covered work with a work licensed
2.559 +under version 3 of the GNU Affero General Public License into a single
2.560 +combined work, and to convey the resulting work. The terms of this
2.561 +License will continue to apply to the part which is the covered work,
2.562 +but the special requirements of the GNU Affero General Public License,
2.563 +section 13, concerning interaction through a network will apply to the
2.564 +combination as such.
2.565 +
2.566 + 14. Revised Versions of this License.
2.567 +
2.568 + The Free Software Foundation may publish revised and/or new versions of
2.569 +the GNU General Public License from time to time. Such new versions will
2.570 +be similar in spirit to the present version, but may differ in detail to
2.571 +address new problems or concerns.
2.572 +
2.573 + Each version is given a distinguishing version number. If the
2.574 +Program specifies that a certain numbered version of the GNU General
2.575 +Public License "or any later version" applies to it, you have the
2.576 +option of following the terms and conditions either of that numbered
2.577 +version or of any later version published by the Free Software
2.578 +Foundation. If the Program does not specify a version number of the
2.579 +GNU General Public License, you may choose any version ever published
2.580 +by the Free Software Foundation.
2.581 +
2.582 + If the Program specifies that a proxy can decide which future
2.583 +versions of the GNU General Public License can be used, that proxy's
2.584 +public statement of acceptance of a version permanently authorizes you
2.585 +to choose that version for the Program.
2.586 +
2.587 + Later license versions may give you additional or different
2.588 +permissions. However, no additional obligations are imposed on any
2.589 +author or copyright holder as a result of your choosing to follow a
2.590 +later version.
2.591 +
2.592 + 15. Disclaimer of Warranty.
2.593 +
2.594 + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
2.595 +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
2.596 +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
2.597 +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
2.598 +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
2.599 +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
2.600 +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
2.601 +ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
2.602 +
2.603 + 16. Limitation of Liability.
2.604 +
2.605 + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2.606 +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
2.607 +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
2.608 +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
2.609 +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
2.610 +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
2.611 +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
2.612 +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
2.613 +SUCH DAMAGES.
2.614 +
2.615 + 17. Interpretation of Sections 15 and 16.
2.616 +
2.617 + If the disclaimer of warranty and limitation of liability provided
2.618 +above cannot be given local legal effect according to their terms,
2.619 +reviewing courts shall apply local law that most closely approximates
2.620 +an absolute waiver of all civil liability in connection with the
2.621 +Program, unless a warranty or assumption of liability accompanies a
2.622 +copy of the Program in return for a fee.
2.623 +
2.624 + END OF TERMS AND CONDITIONS
2.625 +
2.626 + How to Apply These Terms to Your New Programs
2.627 +
2.628 + If you develop a new program, and you want it to be of the greatest
2.629 +possible use to the public, the best way to achieve this is to make it
2.630 +free software which everyone can redistribute and change under these terms.
2.631 +
2.632 + To do so, attach the following notices to the program. It is safest
2.633 +to attach them to the start of each source file to most effectively
2.634 +state the exclusion of warranty; and each file should have at least
2.635 +the "copyright" line and a pointer to where the full notice is found.
2.636 +
2.637 + <one line to give the program's name and a brief idea of what it does.>
2.638 + Copyright (C) <year> <name of author>
2.639 +
2.640 + This program is free software: you can redistribute it and/or modify
2.641 + it under the terms of the GNU General Public License as published by
2.642 + the Free Software Foundation, either version 3 of the License, or
2.643 + (at your option) any later version.
2.644 +
2.645 + This program is distributed in the hope that it will be useful,
2.646 + but WITHOUT ANY WARRANTY; without even the implied warranty of
2.647 + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2.648 + GNU General Public License for more details.
2.649 +
2.650 + You should have received a copy of the GNU General Public License
2.651 + along with this program. If not, see <http://www.gnu.org/licenses/>.
2.652 +
2.653 +Also add information on how to contact you by electronic and paper mail.
2.654 +
2.655 + If the program does terminal interaction, make it output a short
2.656 +notice like this when it starts in an interactive mode:
2.657 +
2.658 + <program> Copyright (C) <year> <name of author>
2.659 + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2.660 + This is free software, and you are welcome to redistribute it
2.661 + under certain conditions; type `show c' for details.
2.662 +
2.663 +The hypothetical commands `show w' and `show c' should show the appropriate
2.664 +parts of the General Public License. Of course, your program's commands
2.665 +might be different; for a GUI interface, you would use an "about box".
2.666 +
2.667 + You should also get your employer (if you work as a programmer) or school,
2.668 +if any, to sign a "copyright disclaimer" for the program, if necessary.
2.669 +For more information on this, and how to apply and follow the GNU GPL, see
2.670 +<http://www.gnu.org/licenses/>.
2.671 +
2.672 + The GNU General Public License does not permit incorporating your program
2.673 +into proprietary programs. If your program is a subroutine library, you
2.674 +may consider it more useful to permit linking proprietary applications with
2.675 +the library. If this is what you want to do, use the GNU Lesser General
2.676 +Public License instead of this License. But first, please read
2.677 +<http://www.gnu.org/philosophy/why-not-lgpl.html>.
2.678 \ No newline at end of file
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/trunk/README Tue Jan 20 10:21:03 2009 +0100
3.3 @@ -0,0 +1,24 @@
3.4 +n3tpd README
3.5 +============
3.6 +
3.7 +Prerequisites:
3.8 +--------------
3.9 +
3.10 +* Java Runtime, Version 1.5
3.11 +* MySQL, Version 5 or higher
3.12 +* Java-MySQL-Connector (JDBC driver)
3.13 +
3.14 +
3.15 +Installation:
3.16 +-------------
3.17 +
3.18 +* Create a database in your DBMS, e.g. named like 'n3tpd_data'
3.19 +* Create the necessary table structure using the helpers/table.sql file
3.20 +* Customize the settings within the n3tpd.conf file
3.21 +* Invoke 'java -jar n3tpd.jar' to start the daemon
3.22 +
3.23 +Bugs and other Issues:
3.24 +----------------------
3.25 +
3.26 +Please mail them to christian.lins@web.de or, better, issue them
3.27 +into our bugtracker at http://bugs.netvader.net/ .
3.28 \ No newline at end of file
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/trunk/TODO Tue Jan 20 10:21:03 2009 +0100
4.3 @@ -0,0 +1,10 @@
4.4 +TODO
4.5 +====
4.6 +
4.7 +* Implement new SQL table structure
4.8 +* Implement a --init-tables command that creates the necessary database/tables
4.9 +
4.10 +ROADMAP
4.11 +=======
4.12 +
4.13 +Version 1.0 must be fully RFC3977 compliant.
4.14 \ No newline at end of file
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/trunk/com/so/news/Config.java Tue Jan 20 10:21:03 2009 +0100
5.3 @@ -0,0 +1,198 @@
5.4 +/*
5.5 + * StarOffice News Server
5.6 + * see AUTHORS for the list of contributors
5.7 + *
5.8 + * This program is free software: you can redistribute it and/or modify
5.9 + * it under the terms of the GNU General Public License as published by
5.10 + * the Free Software Foundation, either version 3 of the License, or
5.11 + * (at your option) any later version.
5.12 + *
5.13 + * This program is distributed in the hope that it will be useful,
5.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
5.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
5.16 + * GNU General Public License for more details.
5.17 + *
5.18 + * You should have received a copy of the GNU General Public License
5.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
5.20 + */
5.21 +
5.22 +package com.so.news;
5.23 +
5.24 +import java.io.FileInputStream;
5.25 +import java.io.FileNotFoundException;
5.26 +import java.io.FileOutputStream;
5.27 +import java.io.IOException;
5.28 +import java.util.Properties;
5.29 +
5.30 +/**
5.31 + * Manages the n3tpd configuration.
5.32 + * @author Christian Lins
5.33 + */
5.34 +public class Config
5.35 +{
5.36 + /** The filename of the logfile */
5.37 + public static final String CONFIG_N3TPD_LOGFILE = "n3tpd.logfile";
5.38 +
5.39 + /** The filename of the config file that is loaded on startup */
5.40 + public static final String FILE = "n3tpd.conf";
5.41 +
5.42 + private static final Properties defaultConfig = new Properties();
5.43 +
5.44 + private static Config instance = null;
5.45 +
5.46 + static
5.47 + {
5.48 + // Set some default values
5.49 + defaultConfig.setProperty("n3tpd.article.lifetime", "300"); // 300 days
5.50 + defaultConfig.setProperty("n3tpd.article.maxsize", "100"); // 100 kbyte
5.51 + defaultConfig.setProperty("n3tpd.port", "119");
5.52 + defaultConfig.setProperty("n3tpd.auxport", "8080");
5.53 + defaultConfig.setProperty("n3tpd.server.backlog", "10");
5.54 + defaultConfig.setProperty("n3tpd.hostname", "localhost");
5.55 + defaultConfig.setProperty("n3tpd.storage.database", "jdbc:mysql://localhost/n3tpd_data");
5.56 + defaultConfig.setProperty("n3tpd.storage.dbmsdriver", "com.mysql.jdbc.Driver");
5.57 + defaultConfig.setProperty("n3tpd.storage.user", "n3tpd_user");
5.58 + defaultConfig.setProperty("n3tpd.storage.password", "mysecret");
5.59 +
5.60 + instance = new Config();
5.61 + }
5.62 +
5.63 + /**
5.64 + * @return A Config instance
5.65 + */
5.66 + public static Config getInstance()
5.67 + {
5.68 + return instance;
5.69 + }
5.70 +
5.71 + // Every config instance is initialized with the default values.
5.72 + private Properties settings = (Properties)defaultConfig.clone();
5.73 +
5.74 + /**
5.75 + * Config is a singelton class with only one instance at time.
5.76 + * So the constructor is private to prevent the creation of more
5.77 + * then one Config instance.
5.78 + * @see Config.getInstance() to retrieve an instance of Config
5.79 + */
5.80 + private Config()
5.81 + {
5.82 + try
5.83 + {
5.84 + // Load settings from file
5.85 + load();
5.86 + }
5.87 + catch(IOException e)
5.88 + {
5.89 + e.printStackTrace();
5.90 + }
5.91 + }
5.92 +
5.93 + /**
5.94 + * Loads the configuration from the config file. By default this is done
5.95 + * by the (private) constructor but it can be useful to reload the config
5.96 + * by invoking this method.
5.97 + * @throws IOException
5.98 + */
5.99 + public void load() throws IOException
5.100 + {
5.101 + try
5.102 + {
5.103 + settings.load(new FileInputStream(FILE));
5.104 + }
5.105 + catch (FileNotFoundException e)
5.106 + {
5.107 + save();
5.108 + }
5.109 + }
5.110 +
5.111 + /**
5.112 + * Saves this Config to the config file. By default this is done
5.113 + * at program end.
5.114 + * @throws FileNotFoundException
5.115 + * @throws IOException
5.116 + */
5.117 + public void save() throws FileNotFoundException, IOException
5.118 + {
5.119 + settings.store(new FileOutputStream(FILE), "N3TPD Config File");
5.120 + }
5.121 +
5.122 + /**
5.123 + * Returns the value that is stored within this config
5.124 + * identified by the given key. If the key cannot be found
5.125 + * the default value is returned.
5.126 + * @param key Key to identify the value.
5.127 + * @param def The default value that is returned if the key
5.128 + * is not found in this Config.
5.129 + * @return
5.130 + */
5.131 + public String get(String key, String def)
5.132 + {
5.133 + return settings.getProperty(key, def);
5.134 + }
5.135 +
5.136 + /**
5.137 + * Returns the value that is stored within this config
5.138 + * identified by the given key. If the key cannot be found
5.139 + * the default value is returned.
5.140 + * @param key Key to identify the value.
5.141 + * @param def The default value that is returned if the key
5.142 + * is not found in this Config.
5.143 + * @return
5.144 + */
5.145 + public int get(String key, int def)
5.146 + {
5.147 + try
5.148 + {
5.149 + String val = get(key);
5.150 + return Integer.parseInt(val);
5.151 + }
5.152 + catch(Exception e)
5.153 + {
5.154 + return def;
5.155 + }
5.156 + }
5.157 +
5.158 + /**
5.159 + * Returns the value that is stored within this config
5.160 + * identified by the given key. If the key cannot be found
5.161 + * the default value is returned.
5.162 + * @param key Key to identify the value.
5.163 + * @param def The default value that is returned if the key
5.164 + * is not found in this Config.
5.165 + * @return
5.166 + */
5.167 + public long get(String key, long def)
5.168 + {
5.169 + try
5.170 + {
5.171 + String val = get(key);
5.172 + return Long.parseLong(val);
5.173 + }
5.174 + catch(Exception e)
5.175 + {
5.176 + return def;
5.177 + }
5.178 + }
5.179 +
5.180 + /**
5.181 + * Returns the value for the given key or null if the
5.182 + * key is not found in this Config.
5.183 + * @param key
5.184 + * @return
5.185 + */
5.186 + private String get(String key)
5.187 + {
5.188 + return settings.getProperty(key);
5.189 + }
5.190 +
5.191 + /**
5.192 + * Sets the value for a given key.
5.193 + * @param key
5.194 + * @param value
5.195 + */
5.196 + public void set(String key, String value)
5.197 + {
5.198 + settings.setProperty(key, value);
5.199 + }
5.200 +
5.201 +}
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/trunk/com/so/news/Debug.java Tue Jan 20 10:21:03 2009 +0100
6.3 @@ -0,0 +1,95 @@
6.4 +/*
6.5 + * StarOffice News Server
6.6 + * see AUTHORS for the list of contributors
6.7 + *
6.8 + * This program is free software: you can redistribute it and/or modify
6.9 + * it under the terms of the GNU General Public License as published by
6.10 + * the Free Software Foundation, either version 3 of the License, or
6.11 + * (at your option) any later version.
6.12 + *
6.13 + * This program is distributed in the hope that it will be useful,
6.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
6.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6.16 + * GNU General Public License for more details.
6.17 + *
6.18 + * You should have received a copy of the GNU General Public License
6.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
6.20 + */
6.21 +
6.22 +package com.so.news;
6.23 +
6.24 +import java.io.FileOutputStream;
6.25 +import java.io.IOException;
6.26 +import java.io.PrintStream;
6.27 +import java.util.Date;
6.28 +
6.29 +/**
6.30 + * Provides logging and debugging methods.
6.31 + * @author Christian Lins
6.32 + */
6.33 +public class Debug
6.34 +{
6.35 + private static Debug instance = null;
6.36 +
6.37 + /**
6.38 + * Returns the singelton instance of this class.
6.39 + */
6.40 + public static Debug getInstance()
6.41 + {
6.42 + if(instance == null)
6.43 + instance = new Debug();
6.44 +
6.45 + return instance;
6.46 + }
6.47 +
6.48 + private PrintStream out = System.err;
6.49 +
6.50 + /**
6.51 + * This class is a singelton class. The constructor is private to prevent
6.52 + * the creation of more than one instance.
6.53 + */
6.54 + private Debug()
6.55 + {
6.56 + try
6.57 + {
6.58 + String filename = Config.getInstance().get(Config.CONFIG_N3TPD_LOGFILE, "n3tpd.log");
6.59 +
6.60 + this.out = new PrintStream(new FileOutputStream(filename));
6.61 + }
6.62 + catch(IOException e)
6.63 + {
6.64 + e.printStackTrace();
6.65 + }
6.66 + }
6.67 +
6.68 + /**
6.69 + * Returns the debug output PrintStream. By default this is System.err.
6.70 + */
6.71 + public PrintStream getStream()
6.72 + {
6.73 + return out;
6.74 + }
6.75 +
6.76 + /**
6.77 + * Writes the given message to the debug output.
6.78 + * @param msg A String message or an object.
6.79 + */
6.80 + public void log(Object msg)
6.81 + {
6.82 + log(out, msg);
6.83 + log(System.out, msg);
6.84 + }
6.85 +
6.86 + /**
6.87 + * Writes the given debug message to the given PrintStream.
6.88 + * @param out
6.89 + * @param msg
6.90 + */
6.91 + public void log(PrintStream out, Object msg)
6.92 + {
6.93 + out.print(new Date().toString());
6.94 + out.print(": ");
6.95 + out.println(msg.toString());
6.96 + out.flush();
6.97 + }
6.98 +}
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/trunk/com/so/news/Main.java Tue Jan 20 10:21:03 2009 +0100
7.3 @@ -0,0 +1,96 @@
7.4 +/*
7.5 + * StarOffice News Server
7.6 + * see AUTHORS for the list of contributors
7.7 + *
7.8 + * This program is free software: you can redistribute it and/or modify
7.9 + * it under the terms of the GNU General Public License as published by
7.10 + * the Free Software Foundation, either version 3 of the License, or
7.11 + * (at your option) any later version.
7.12 + *
7.13 + * This program is distributed in the hope that it will be useful,
7.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
7.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
7.16 + * GNU General Public License for more details.
7.17 + *
7.18 + * You should have received a copy of the GNU General Public License
7.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
7.20 + */
7.21 +
7.22 +package com.so.news;
7.23 +
7.24 +import java.net.BindException;
7.25 +
7.26 +import java.sql.Driver;
7.27 +import java.sql.DriverManager;
7.28 +import java.util.Enumeration;
7.29 +
7.30 +import com.so.news.storage.Database;
7.31 +import com.so.news.storage.Purger;
7.32 +
7.33 +/**
7.34 + * Startup class of the daemon.
7.35 + * @author Christian Lins
7.36 + */
7.37 +public class Main
7.38 +{
7.39 + /** Version information of the StarOffice News daemon */
7.40 + public static final String VERSION = "StarOffice News Server 0.5alpha1";
7.41 +
7.42 + /**
7.43 + * The main entrypoint.
7.44 + * @param args
7.45 + * @throws Exception
7.46 + */
7.47 + public static void main(String args[]) throws Exception
7.48 + {
7.49 + System.out.println(VERSION);
7.50 +
7.51 + // Command line arguments
7.52 + boolean auxPort = false;
7.53 +
7.54 + for(int n = 0; n < args.length; n++)
7.55 + {
7.56 + if(args[n].equals("--dumpjdbcdriver"))
7.57 + {
7.58 + System.out.println("Available JDBC drivers:");
7.59 + Enumeration<Driver> drvs = DriverManager.getDrivers();
7.60 + while(drvs.hasMoreElements())
7.61 + System.out.println(drvs.nextElement());
7.62 + return;
7.63 + }
7.64 + else if(args[n].equals("--useaux"))
7.65 + auxPort = true;
7.66 + }
7.67 +
7.68 + // Try to load the Database
7.69 + try
7.70 + {
7.71 + Database.arise();
7.72 + }
7.73 + catch(Exception ex)
7.74 + {
7.75 + ex.printStackTrace(Debug.getInstance().getStream());
7.76 + System.err.println("Database initialization failed with " + ex.toString());
7.77 +
7.78 + return;
7.79 + }
7.80 +
7.81 + // Start the n3tpd garbage collector
7.82 + new Purger().start();
7.83 +
7.84 + // Start the listening daemon
7.85 + try
7.86 + {
7.87 + new NNTPDaemon(false).start();
7.88 + }
7.89 + catch(BindException ex)
7.90 + {
7.91 + ex.printStackTrace(Debug.getInstance().getStream());
7.92 + System.err.println("Could not bind to interface. Perhaps you need superuser rights?");
7.93 + }
7.94 +
7.95 + // Start auxilary listening port...
7.96 + if(auxPort)
7.97 + new NNTPDaemon(true).start();
7.98 + }
7.99 +}
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/trunk/com/so/news/NNTPConnection.java Tue Jan 20 10:21:03 2009 +0100
8.3 @@ -0,0 +1,395 @@
8.4 +/*
8.5 + * StarOffice News Server
8.6 + * see AUTHORS for the list of contributors
8.7 + *
8.8 + * This program is free software: you can redistribute it and/or modify
8.9 + * it under the terms of the GNU General Public License as published by
8.10 + * the Free Software Foundation, either version 3 of the License, or
8.11 + * (at your option) any later version.
8.12 + *
8.13 + * This program is distributed in the hope that it will be useful,
8.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
8.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
8.16 + * GNU General Public License for more details.
8.17 + *
8.18 + * You should have received a copy of the GNU General Public License
8.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
8.20 + */
8.21 +
8.22 +package com.so.news;
8.23 +
8.24 +import java.io.BufferedReader;
8.25 +import java.io.BufferedWriter;
8.26 +import java.io.File;
8.27 +import java.io.InputStreamReader;
8.28 +import java.io.IOException;
8.29 +import java.io.OutputStreamWriter;
8.30 +import java.net.Socket;
8.31 +import java.net.SocketException;
8.32 +import java.text.SimpleDateFormat;
8.33 +import java.util.Date;
8.34 +import java.util.LinkedList;
8.35 +import java.util.List;
8.36 +import com.so.news.command.ArticleCommand;
8.37 +import com.so.news.command.GroupCommand;
8.38 +import com.so.news.command.ListCommand;
8.39 +import com.so.news.command.PostCommand;
8.40 +import com.so.news.command.OverCommand;
8.41 +import com.so.news.storage.Article;
8.42 +import com.so.news.storage.Group;
8.43 +
8.44 +/**
8.45 + * Represents the connection between the server and one client.
8.46 + * @author Christian Lins (christian.lins@web.de)
8.47 + */
8.48 +public class NNTPConnection extends Thread
8.49 +{
8.50 + public static final String NEWLINE = "\r\n";
8.51 + public static final String MESSAGE_ID_PATTERN = "<[^>]+>";
8.52 +
8.53 + private boolean debug
8.54 + = Boolean.parseBoolean(Config.getInstance().get("n3tpd.debug", "false"));
8.55 + private Socket socket;
8.56 + private boolean exit = false;
8.57 + private BufferedWriter out;
8.58 + private BufferedReader in;
8.59 + private Article currentArticle = null;
8.60 + private Group currentGroup = null;
8.61 +
8.62 + /**
8.63 + * Creates a new NNTPConnection instance using the given connected Socket.
8.64 + * @param socket
8.65 + * @throws java.io.IOException
8.66 + */
8.67 + public NNTPConnection(Socket socket)
8.68 + throws IOException
8.69 + {
8.70 + this.socket = socket;
8.71 + this.in = new BufferedReader(new InputStreamReader(socket.getInputStream()));
8.72 + this.out = new BufferedWriter(new OutputStreamWriter(socket.getOutputStream()));
8.73 + // TODO: The output stream should be of type PrintStream so that many
8.74 + // of the printX() methods of this class can go to trash
8.75 +
8.76 + setDaemon(true); // Exits if the main thread is killed
8.77 + }
8.78 +
8.79 + /**
8.80 + * Closes the associated socket end exits the Thread.
8.81 + */
8.82 + public void exit()
8.83 + {
8.84 + try
8.85 + {
8.86 + exit = true;
8.87 + socket.close();
8.88 + }
8.89 + catch (Exception e)
8.90 + {
8.91 + e.printStackTrace();
8.92 + }
8.93 + }
8.94 +
8.95 + /**
8.96 + * Prints a CharSequence to the sockets output stream.
8.97 + */
8.98 + public void print(CharSequence s) throws IOException
8.99 + {
8.100 + out.append(s);
8.101 + }
8.102 +
8.103 + public void println(CharSequence s) throws IOException
8.104 + {
8.105 + print(s);
8.106 + print(NEWLINE);
8.107 + if (debug)
8.108 + System.out.println("<<< " + s);
8.109 + }
8.110 +
8.111 + public void printStatus(int code, String description) throws IOException
8.112 + {
8.113 + println("" + code + " " + description);
8.114 + flush();
8.115 + }
8.116 +
8.117 + public void printTextLine(CharSequence line) throws IOException
8.118 + {
8.119 + if (line.length() > 0 && line.charAt(0) == '.')
8.120 + print("..");
8.121 + println(line);
8.122 + }
8.123 +
8.124 + public void printTextPart(CharSequence text) throws IOException
8.125 + {
8.126 + String[] lines = text.toString().split(NEWLINE);
8.127 + for (String line : lines)
8.128 + printTextLine(line);
8.129 + }
8.130 +
8.131 + public void printText(CharSequence text) throws IOException
8.132 + {
8.133 + printTextPart(text);
8.134 + println(".");
8.135 + flush();
8.136 + }
8.137 +
8.138 + public void flush() throws IOException
8.139 + {
8.140 + out.flush();
8.141 + }
8.142 +
8.143 + public String readln() throws IOException
8.144 + {
8.145 + String s = in.readLine();
8.146 + if (s == null)
8.147 + throw new IOException("Socket closed");
8.148 + if (debug)
8.149 + System.out.println(">>> " + s);
8.150 + return s;
8.151 + }
8.152 +
8.153 + public String[] readCommand() throws IOException
8.154 + {
8.155 + return readln().split("[ ]+");
8.156 + }
8.157 +
8.158 + public List<String> readText() throws IOException
8.159 + {
8.160 + List<String> l = new LinkedList<String>();
8.161 + String s;
8.162 + do
8.163 + {
8.164 + s = readln();
8.165 + if (!s.equals("."))
8.166 + {
8.167 + if (s.startsWith(".."))
8.168 + s = s.substring(1);
8.169 + l.add(s);
8.170 + }
8.171 + }
8.172 + while (!s.equals("."));
8.173 + return l;
8.174 + }
8.175 +
8.176 + public String readTextLine() throws IOException
8.177 + {
8.178 + String s = null;
8.179 + do
8.180 + {
8.181 + s = readln();
8.182 + }
8.183 + while (s == null);
8.184 + if (s.equals("."))
8.185 + return null;
8.186 + if (s.startsWith(".."))
8.187 + s = s.substring(1);
8.188 + return s;
8.189 + }
8.190 +
8.191 + public void setCurrentArticle(Article current)
8.192 + {
8.193 + currentArticle = current;
8.194 + }
8.195 +
8.196 + public Article getCurrentArticle()
8.197 + {
8.198 + return currentArticle;
8.199 + }
8.200 +
8.201 + public void setCurrentGroup(Group current)
8.202 + {
8.203 + currentGroup = current;
8.204 + }
8.205 +
8.206 + public Group getCurrentGroup()
8.207 + {
8.208 + return currentGroup;
8.209 + }
8.210 +
8.211 + private void processCommand(String[] command)
8.212 + throws Exception
8.213 + {
8.214 + if (command.length == 0)
8.215 + return; // TODO Error
8.216 +
8.217 + String commandName = command[0];
8.218 +
8.219 + // RFC977
8.220 + // TODO HELP command
8.221 + // TODO NEWGROUPS command
8.222 + // TODO NEWNEWS command
8.223 +
8.224 + // RFC2980
8.225 + // TODO LIST ACTIVE command
8.226 + // TODO LIST ACTIVE.TIMES command
8.227 + // TODO LIST DISTRIBUTIONS command
8.228 + // TODO LIST DISTRIB.PATS command
8.229 + // TODO XGTITLE command
8.230 + // TODO XHDR command
8.231 + // TODO XPAT command
8.232 + // TODO XPATH command
8.233 + // TODO XROVER command
8.234 + // TODO XTHREAD command
8.235 + // TODO AUTHINFO command
8.236 +
8.237 + // STANDARD COMMANDS
8.238 + if (commandName.equalsIgnoreCase("ARTICLE")
8.239 + || commandName.equalsIgnoreCase("STAT")
8.240 + || commandName.equalsIgnoreCase("HEAD")
8.241 + || commandName.equalsIgnoreCase("BODY"))
8.242 + {
8.243 + ArticleCommand cmd = new ArticleCommand(this);
8.244 + cmd.process(command);
8.245 + }
8.246 +
8.247 + else if (commandName.equalsIgnoreCase("LIST"))
8.248 + {
8.249 + ListCommand cmd = new ListCommand(this);
8.250 + cmd.process(command);
8.251 + }
8.252 +
8.253 + else if (commandName.equalsIgnoreCase("GROUP"))
8.254 + {
8.255 + GroupCommand cmd = new GroupCommand(this);
8.256 + cmd.process(command);
8.257 + }
8.258 +
8.259 + else if(commandName.equalsIgnoreCase("POST"))
8.260 + {
8.261 + PostCommand cmd = new PostCommand(this);
8.262 + cmd.process(command);
8.263 + }
8.264 +
8.265 + else if (commandName.equalsIgnoreCase("CHECK")
8.266 + || commandName.equalsIgnoreCase("TAKETHIS"))
8.267 + {
8.268 + // untested, RFC2980 compliant
8.269 + printStatus(400, "not accepting articles");
8.270 + return;
8.271 + }
8.272 +
8.273 + else if (commandName.equalsIgnoreCase("IHAVE")
8.274 + || commandName.equalsIgnoreCase("XREPLIC"))
8.275 + {
8.276 + // untested, RFC977 compliant
8.277 + printStatus(435, "article not wanted - do not send it");
8.278 + return;
8.279 + }
8.280 +
8.281 + else if (commandName.equalsIgnoreCase("XCREATEGROUP"))
8.282 + {
8.283 + return;
8.284 + }
8.285 +
8.286 + else if (commandName.equalsIgnoreCase("SLAVE"))
8.287 + {
8.288 + // untested, RFC977 compliant
8.289 + printStatus(202, "slave status noted");
8.290 + return;
8.291 + }
8.292 +
8.293 + else if (commandName.equalsIgnoreCase("XINDEX"))
8.294 + {
8.295 + // untested, RFC2980 compliant
8.296 + printStatus(418, "no tin-style index is available for this news group");
8.297 + return;
8.298 + }
8.299 +
8.300 + else if (commandName.equalsIgnoreCase("DATE"))
8.301 + {
8.302 + printStatus(111, new SimpleDateFormat("yyyyMMddHHmmss")
8.303 + .format(new Date()));
8.304 + return;
8.305 + }
8.306 +
8.307 + else if (commandName.equalsIgnoreCase("MODE"))
8.308 + {
8.309 + if (command[1].equalsIgnoreCase("READER"))
8.310 + {
8.311 + // untested, RFC2980 compliant
8.312 + printStatus(200, "Hello, you can post");
8.313 + }
8.314 + else if (command[1].equalsIgnoreCase("STREAM"))
8.315 + {
8.316 + printStatus(203, "Streaming is OK");
8.317 + }
8.318 + else
8.319 + printStatus(501, "Command not supported");
8.320 + }
8.321 +
8.322 + else if (commandName.equalsIgnoreCase("QUIT"))
8.323 + {
8.324 + // untested, RFC977 compliant
8.325 + printStatus(205, "closing connection - goodbye!");
8.326 + exit();
8.327 + return;
8.328 + }
8.329 +
8.330 + else if (commandName.equalsIgnoreCase("XSHUTDOWN"))
8.331 + {
8.332 + printStatus(205, "closing connection - goodbye!");
8.333 + exit();
8.334 + return;
8.335 + }
8.336 +
8.337 + // X COMMANDS
8.338 + else if(commandName.equalsIgnoreCase("XOVER")
8.339 + || commandName.equalsIgnoreCase("OVER"))
8.340 + {
8.341 + OverCommand cmd = new OverCommand(this);
8.342 + cmd.process(command);
8.343 + }
8.344 +
8.345 + else
8.346 + printStatus(501, "Command not supported");
8.347 + }
8.348 +
8.349 + /**
8.350 + * Runloop of this Thread.
8.351 + * @throws RuntimeException if this method is called directly.
8.352 + */
8.353 + @Override
8.354 + public void run()
8.355 + {
8.356 + assert !this.equals(Thread.currentThread());
8.357 +
8.358 + try
8.359 + {
8.360 + printStatus(200, Config.getInstance().get("n3tpd.hostname", "localhost")
8.361 + + " " + Main.VERSION + " news server ready - (posting ok).");
8.362 + }
8.363 + catch (IOException e1)
8.364 + {
8.365 + exit();
8.366 + }
8.367 +
8.368 + while (!exit)
8.369 + {
8.370 + try
8.371 + {
8.372 + processCommand(readCommand());
8.373 + }
8.374 + catch (SocketException e)
8.375 + {
8.376 + if (exit)
8.377 + return;
8.378 + exit();
8.379 + e.printStackTrace();
8.380 + }
8.381 + catch (IOException e)
8.382 + {
8.383 + if (exit)
8.384 + return;
8.385 + exit();
8.386 + e.printStackTrace();
8.387 + }
8.388 + catch (Throwable e)
8.389 + {
8.390 + if (exit)
8.391 + return;
8.392 + e.printStackTrace();
8.393 + // silently ignore
8.394 + }
8.395 + }
8.396 + }
8.397 +
8.398 +}
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/trunk/com/so/news/NNTPDaemon.java Tue Jan 20 10:21:03 2009 +0100
9.3 @@ -0,0 +1,64 @@
9.4 +/*
9.5 + * StarOffice News Server
9.6 + * see AUTHORS for the list of contributors
9.7 + *
9.8 + * This program is free software: you can redistribute it and/or modify
9.9 + * it under the terms of the GNU General Public License as published by
9.10 + * the Free Software Foundation, either version 3 of the License, or
9.11 + * (at your option) any later version.
9.12 + *
9.13 + * This program is distributed in the hope that it will be useful,
9.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
9.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
9.16 + * GNU General Public License for more details.
9.17 + *
9.18 + * You should have received a copy of the GNU General Public License
9.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
9.20 + */
9.21 +
9.22 +package com.so.news;
9.23 +
9.24 +import java.io.IOException;
9.25 +import java.net.ServerSocket;
9.26 +
9.27 +/**
9.28 + * Server component of the n3tpd.
9.29 + * @author Christian Lins
9.30 + * @author Dennis Schwerdel
9.31 + */
9.32 +public class NNTPDaemon extends Thread
9.33 +{
9.34 + private ServerSocket socket;
9.35 +
9.36 + public NNTPDaemon(boolean aux) throws IOException
9.37 + {
9.38 + int port;
9.39 + if(!aux)
9.40 + port = Config.getInstance().get("n3tpd.port", 119);
9.41 + else
9.42 + port = Config.getInstance().get("n3tpd.auxport", 8080);
9.43 +
9.44 + int backlog = Config.getInstance().get("n3tpd.server.backlog", 10);
9.45 +
9.46 + // Create and bind the socket
9.47 + socket = new ServerSocket(port, backlog);
9.48 + }
9.49 +
9.50 + @Override
9.51 + public void run()
9.52 + {
9.53 + System.out.println("Daemon listening on port " + socket.getLocalPort() + " ...");
9.54 +
9.55 + while(isAlive() && !isInterrupted())
9.56 + {
9.57 + try
9.58 + {
9.59 + new NNTPConnection(socket.accept()).start();
9.60 + }
9.61 + catch (Exception e)
9.62 + {
9.63 + e.printStackTrace();
9.64 + }
9.65 + }
9.66 + }
9.67 +}
10.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
10.2 +++ b/trunk/com/so/news/command/ArticleCommand.java Tue Jan 20 10:21:03 2009 +0100
10.3 @@ -0,0 +1,124 @@
10.4 +/*
10.5 + * StarOffice News Server
10.6 + * see AUTHORS for the list of contributors
10.7 + *
10.8 + * This program is free software: you can redistribute it and/or modify
10.9 + * it under the terms of the GNU General Public License as published by
10.10 + * the Free Software Foundation, either version 3 of the License, or
10.11 + * (at your option) any later version.
10.12 + *
10.13 + * This program is distributed in the hope that it will be useful,
10.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
10.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10.16 + * GNU General Public License for more details.
10.17 + *
10.18 + * You should have received a copy of the GNU General Public License
10.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
10.20 + */
10.21 +
10.22 +package com.so.news.command;
10.23 +
10.24 +import java.io.IOException;
10.25 +import java.text.SimpleDateFormat;
10.26 +import java.util.Locale;
10.27 +import java.util.Map;
10.28 +import com.so.news.Debug;
10.29 +import com.so.news.NNTPConnection;
10.30 +import com.so.news.storage.Article;
10.31 +
10.32 +/**
10.33 + * Class handling the ARTICLE command.
10.34 + * @author Christian Lins
10.35 + * @author Dennis Schwerdel
10.36 + */
10.37 +public class ArticleCommand extends Command
10.38 +{
10.39 + public ArticleCommand(NNTPConnection connection)
10.40 + {
10.41 + super(connection);
10.42 + }
10.43 +
10.44 + public boolean process(String[] command) throws IOException
10.45 + {
10.46 + String commandName = command[0];
10.47 +
10.48 + // untested, RFC977 compliant
10.49 + Article article = null;
10.50 + if (command.length <= 1)
10.51 + {
10.52 + article = getCurrentArticle();
10.53 + if (article == null)
10.54 + {
10.55 + printStatus(420, "no current article has been selected");
10.56 + return true;
10.57 + }
10.58 + }
10.59 + else if (command[1].matches(NNTPConnection.MESSAGE_ID_PATTERN))
10.60 + {
10.61 + // Message-ID
10.62 + article = Article.getByMessageID(command[1]);
10.63 + if (article == null)
10.64 + {
10.65 + printStatus(430, "no such article found");
10.66 + return true;
10.67 + }
10.68 + }
10.69 + else
10.70 + {
10.71 + // Message Number
10.72 + try
10.73 + {
10.74 + int num = Integer.parseInt(command[1]);
10.75 + article = Article.getByNumberInGroup(connection.getCurrentGroup(), num);
10.76 + }
10.77 + catch (Exception ex)
10.78 + {
10.79 + ex.printStackTrace(Debug.getInstance().getStream());
10.80 + System.err.println(ex.getLocalizedMessage());
10.81 + }
10.82 + if (article == null)
10.83 + {
10.84 + printStatus(423, "no such article number in this group");
10.85 + return true;
10.86 + }
10.87 + setCurrentArticle(article);
10.88 + }
10.89 +
10.90 + if (commandName.equalsIgnoreCase("ARTICLE"))
10.91 + {
10.92 + printStatus(220, article.getNumberInGroup() + " " + article.getMessageID()
10.93 + + " article retrieved - head and body follow");
10.94 + Map<String, String> header = article.getHeader();
10.95 + for(Map.Entry<String, String> entry : header.entrySet())
10.96 + {
10.97 + if(entry.getKey().equals("Date"))
10.98 + {
10.99 + SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
10.100 + printTextPart("Date: " + sdf.format(article.getDate()));
10.101 + }
10.102 + else
10.103 + printTextPart(entry.getKey() + ": " + entry.getValue());
10.104 + }
10.105 + println("");
10.106 + printText(article.getBody());
10.107 + }
10.108 + else if (commandName.equalsIgnoreCase("HEAD"))
10.109 + {
10.110 + printStatus(500, "No longer supported! Use XOVER instead.");
10.111 + return false;
10.112 + }
10.113 + else if (commandName.equalsIgnoreCase("BODY"))
10.114 + {
10.115 + printStatus(222, article.getNumberInGroup() + " " + article.getMessageID()
10.116 + + " body");
10.117 + printText(article.getBody());
10.118 + }
10.119 + else if (commandName.equalsIgnoreCase("STAT"))
10.120 + {
10.121 + printStatus(223, article.getNumberInGroup() + " " + article.getMessageID()
10.122 + + " article retrieved - request text separately");
10.123 + }
10.124 + return true;
10.125 + }
10.126 +
10.127 +}
11.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
11.2 +++ b/trunk/com/so/news/command/CapabilitiesCommand.java Tue Jan 20 10:21:03 2009 +0100
11.3 @@ -0,0 +1,50 @@
11.4 +/*
11.5 + * StarOffice News Server
11.6 + * see AUTHORS for the list of contributors
11.7 + *
11.8 + * This program is free software: you can redistribute it and/or modify
11.9 + * it under the terms of the GNU General Public License as published by
11.10 + * the Free Software Foundation, either version 3 of the License, or
11.11 + * (at your option) any later version.
11.12 + *
11.13 + * This program is distributed in the hope that it will be useful,
11.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
11.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11.16 + * GNU General Public License for more details.
11.17 + *
11.18 + * You should have received a copy of the GNU General Public License
11.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
11.20 + */
11.21 +
11.22 +package com.so.news.command;
11.23 +
11.24 +import com.so.news.NNTPConnection;
11.25 +
11.26 +/**
11.27 + * The CAPABILITIES command allows a client to determine the
11.28 + capabilities of the server at any given time.
11.29 +
11.30 + This command MAY be issued at any time; the server MUST NOT require
11.31 + it to be issued in order to make use of any capability. The response
11.32 + generated by this command MAY change during a session because of
11.33 + other state information (which, in turn, may be changed by the
11.34 + effects of other commands or by external events). An NNTP client is
11.35 + only able to get the current and correct information concerning
11.36 + available capabilities at any point during a session by issuing a
11.37 + CAPABILITIES command at that point of that session and processing the
11.38 + response.
11.39 + * @author chris
11.40 + */
11.41 +public class CapabilitiesCommand extends Command
11.42 +{
11.43 + public CapabilitiesCommand(NNTPConnection connection)
11.44 + {
11.45 + super(connection);
11.46 + }
11.47 +
11.48 + public boolean process(String[] command)
11.49 + throws Exception
11.50 + {
11.51 + return false;
11.52 + }
11.53 +}
12.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
12.2 +++ b/trunk/com/so/news/command/Command.java Tue Jan 20 10:21:03 2009 +0100
12.3 @@ -0,0 +1,106 @@
12.4 +/*
12.5 + * StarOffice News Server
12.6 + * see AUTHORS for the list of contributors
12.7 + *
12.8 + * This program is free software: you can redistribute it and/or modify
12.9 + * it under the terms of the GNU General Public License as published by
12.10 + * the Free Software Foundation, either version 3 of the License, or
12.11 + * (at your option) any later version.
12.12 + *
12.13 + * This program is distributed in the hope that it will be useful,
12.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
12.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12.16 + * GNU General Public License for more details.
12.17 + *
12.18 + * You should have received a copy of the GNU General Public License
12.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
12.20 + */
12.21 +
12.22 +package com.so.news.command;
12.23 +
12.24 +import java.io.IOException;
12.25 +import java.util.List;
12.26 +import com.so.news.NNTPConnection;
12.27 +import com.so.news.storage.Article;
12.28 +import com.so.news.storage.Group;
12.29 +
12.30 +/**
12.31 + * Base class for all command handling classes.
12.32 + * @author Christian Lins
12.33 + * @author Dennis Schwerdel
12.34 + */
12.35 +public abstract class Command
12.36 +{
12.37 + protected NNTPConnection connection;
12.38 +
12.39 + public Command(NNTPConnection connection)
12.40 + {
12.41 + this.connection = connection;
12.42 + }
12.43 +
12.44 + protected static String NEWLINE = NNTPConnection.NEWLINE;
12.45 +
12.46 + protected List<String> readText()
12.47 + throws IOException
12.48 + {
12.49 + return connection.readText();
12.50 + }
12.51 +
12.52 + protected String readTextLine() throws IOException
12.53 + {
12.54 + return connection.readTextLine();
12.55 + }
12.56 +
12.57 + protected void printStatus(int status, String text) throws IOException
12.58 + {
12.59 + connection.printStatus(status, text);
12.60 + }
12.61 +
12.62 + protected void printTextLine(CharSequence text) throws IOException
12.63 + {
12.64 + connection.printTextLine(text);
12.65 + }
12.66 +
12.67 + protected void printTextPart(CharSequence text) throws IOException
12.68 + {
12.69 + connection.printTextPart(text);
12.70 + }
12.71 +
12.72 + protected void printText(CharSequence text) throws IOException
12.73 + {
12.74 + connection.printText(text);
12.75 + }
12.76 +
12.77 + protected void println(CharSequence text) throws IOException
12.78 + {
12.79 + connection.println(text);
12.80 + }
12.81 +
12.82 + protected void flush() throws IOException
12.83 + {
12.84 + connection.flush();
12.85 + }
12.86 +
12.87 + protected Article getCurrentArticle()
12.88 + {
12.89 + return connection.getCurrentArticle();
12.90 + }
12.91 +
12.92 + protected Group getCurrentGroup()
12.93 + {
12.94 + return connection.getCurrentGroup();
12.95 + }
12.96 +
12.97 + protected void setCurrentArticle(Article current)
12.98 + {
12.99 + connection.setCurrentArticle(current);
12.100 + }
12.101 +
12.102 + protected void setCurrentGroup(Group current)
12.103 + {
12.104 + connection.setCurrentGroup(current);
12.105 + }
12.106 +
12.107 + public abstract boolean process(String[] command)
12.108 + throws Exception;
12.109 +}
13.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
13.2 +++ b/trunk/com/so/news/command/GroupCommand.java Tue Jan 20 10:21:03 2009 +0100
13.3 @@ -0,0 +1,60 @@
13.4 +/*
13.5 + * StarOffice News Server
13.6 + * see AUTHORS for the list of contributors
13.7 + *
13.8 + * This program is free software: you can redistribute it and/or modify
13.9 + * it under the terms of the GNU General Public License as published by
13.10 + * the Free Software Foundation, either version 3 of the License, or
13.11 + * (at your option) any later version.
13.12 + *
13.13 + * This program is distributed in the hope that it will be useful,
13.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
13.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13.16 + * GNU General Public License for more details.
13.17 + *
13.18 + * You should have received a copy of the GNU General Public License
13.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
13.20 + */
13.21 +
13.22 +package com.so.news.command;
13.23 +
13.24 +import com.so.news.NNTPConnection;
13.25 +import com.so.news.storage.Group;
13.26 +
13.27 +/**
13.28 + * Class handling the GROUP command.
13.29 + * @author Christian Lins
13.30 + * @author Dennis Schwerdel
13.31 + */
13.32 +public class GroupCommand extends Command
13.33 +{
13.34 + public GroupCommand(NNTPConnection conn)
13.35 + {
13.36 + super(conn);
13.37 + }
13.38 +
13.39 + public boolean process(String[] command)
13.40 + throws Exception
13.41 + {
13.42 + // untested, RFC977 compliant
13.43 + Group g = null;
13.44 + if (command.length >= 2)
13.45 + {
13.46 + g = Group.getByName(command[1]);
13.47 + }
13.48 + if (g == null)
13.49 + {
13.50 + printStatus(411, "no such news group");
13.51 + return true;
13.52 + }
13.53 + else
13.54 + {
13.55 + setCurrentGroup(g);
13.56 +
13.57 + printStatus(211, g.getEstimatedArticleCount() + " " + g.getFirstArticle()
13.58 + + " " + g.getLastArticle() + " " + g.getName() + " group selected");
13.59 + return true;
13.60 + }
13.61 + }
13.62 +
13.63 +}
14.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
14.2 +++ b/trunk/com/so/news/command/ListCommand.java Tue Jan 20 10:21:03 2009 +0100
14.3 @@ -0,0 +1,92 @@
14.4 +/*
14.5 + * StarOffice News Server
14.6 + * see AUTHORS for the list of contributors
14.7 + *
14.8 + * This program is free software: you can redistribute it and/or modify
14.9 + * it under the terms of the GNU General Public License as published by
14.10 + * the Free Software Foundation, either version 3 of the License, or
14.11 + * (at your option) any later version.
14.12 + *
14.13 + * This program is distributed in the hope that it will be useful,
14.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
14.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14.16 + * GNU General Public License for more details.
14.17 + *
14.18 + * You should have received a copy of the GNU General Public License
14.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
14.20 + */
14.21 +
14.22 +package com.so.news.command;
14.23 +
14.24 +import java.io.IOException;
14.25 +import java.util.ArrayList;
14.26 +import com.so.news.NNTPConnection;
14.27 +import com.so.news.storage.Group;
14.28 +
14.29 +/**
14.30 + * Class handling the LIST command.
14.31 + * @author Christian Lins
14.32 + * @author Dennis Schwerdel
14.33 + */
14.34 +public class ListCommand extends Command
14.35 +{
14.36 + public ListCommand(NNTPConnection conn)
14.37 + {
14.38 + super(conn);
14.39 + }
14.40 +
14.41 + public boolean process(String[] command)
14.42 + throws Exception
14.43 + {
14.44 + if (command.length >= 2)
14.45 + {
14.46 + if (command[1].equalsIgnoreCase("OVERVIEW.FMT"))
14.47 + {
14.48 + printStatus(215, "information follows");
14.49 + printText("Subject:\nFrom:\nDate:\nMessage-ID:\nReferences:\nBytes:\nLines:");
14.50 + return true;
14.51 + }
14.52 + if (command[1].equalsIgnoreCase("NEWSGROUPS"))
14.53 + {
14.54 + printStatus(215, "information follows");
14.55 + ArrayList<Group> list = Group.getAll();
14.56 + for (Group g : list)
14.57 + {
14.58 + printTextLine(g.getName() + "\t" + "-");
14.59 + }
14.60 + println(".");
14.61 + flush();
14.62 + return true;
14.63 + }
14.64 + if (command[1].equalsIgnoreCase("SUBSCRIPTIONS"))
14.65 + {
14.66 + printStatus(215, "information follows");
14.67 + println(".");
14.68 + flush();
14.69 + return true;
14.70 + }
14.71 + if (command[1].equalsIgnoreCase("EXTENSIONS"))
14.72 + {
14.73 + printStatus(202, "Supported NNTP extensions.");
14.74 + printTextLine("LISTGROUP");
14.75 + println(".");
14.76 + flush();
14.77 + return true;
14.78 + }
14.79 + return false;
14.80 + }
14.81 + printStatus(215, "list of newsgroups follows");
14.82 + for (Group g : Group.getAll())
14.83 + {
14.84 + //if(g.getEstimatedArticleCount() <= 0)
14.85 + // continue;
14.86 +
14.87 + printTextLine(g.getName() + " " + g.getLastArticle() + " "
14.88 + + g.getFirstArticle() + " y");
14.89 + }
14.90 + println(".");
14.91 + flush();
14.92 + return true;
14.93 + }
14.94 +
14.95 +}
15.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
15.2 +++ b/trunk/com/so/news/command/ListGroupCommand.java Tue Jan 20 10:21:03 2009 +0100
15.3 @@ -0,0 +1,71 @@
15.4 +/*
15.5 + * StarOffice News Server
15.6 + * see AUTHORS for the list of contributors
15.7 + *
15.8 + * This program is free software: you can redistribute it and/or modify
15.9 + * it under the terms of the GNU General Public License as published by
15.10 + * the Free Software Foundation, either version 3 of the License, or
15.11 + * (at your option) any later version.
15.12 + *
15.13 + * This program is distributed in the hope that it will be useful,
15.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
15.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15.16 + * GNU General Public License for more details.
15.17 + *
15.18 + * You should have received a copy of the GNU General Public License
15.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
15.20 + */
15.21 +
15.22 +package com.so.news.command;
15.23 +
15.24 +import java.util.List;
15.25 +import com.so.news.NNTPConnection;
15.26 +import com.so.news.storage.Article;
15.27 +import com.so.news.storage.Group;
15.28 +
15.29 +/**
15.30 + * Class handling the LISTGROUP command.
15.31 + * @author Christian Lins
15.32 + * @author Dennis Schwerdel
15.33 + */
15.34 +public class ListGroupCommand extends Command
15.35 +{
15.36 + public ListGroupCommand(NNTPConnection conn)
15.37 + {
15.38 + super(conn);
15.39 + }
15.40 +
15.41 + public boolean process(String[] command)
15.42 + throws Exception
15.43 + {
15.44 + String commandName = command[0];
15.45 + if (!commandName.equalsIgnoreCase("LISTGROUP"))
15.46 + return false;
15.47 + // untested, RFC977 complient
15.48 + Group group = null;
15.49 + if (command.length >= 2)
15.50 + {
15.51 + group = Group.getByName(command[1]);
15.52 + }
15.53 + else
15.54 + {
15.55 + group = getCurrentGroup();
15.56 + }
15.57 + if (group == null)
15.58 + {
15.59 + printStatus(412, "Not currently in newsgroup");
15.60 + return true;
15.61 + }
15.62 + List<Article> list = group.getAllArticles();
15.63 + printStatus(211, "list of article numbers follow"); // argh, bad english in
15.64 + // RFC
15.65 + for (Article a : list)
15.66 + {
15.67 + printTextLine("" + a.getNumberInGroup());
15.68 + }
15.69 + println(".");
15.70 + flush();
15.71 + return true;
15.72 + }
15.73 +
15.74 +}
16.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
16.2 +++ b/trunk/com/so/news/command/NewGroupsCommand.java Tue Jan 20 10:21:03 2009 +0100
16.3 @@ -0,0 +1,68 @@
16.4 +/*
16.5 + * StarOffice News Server
16.6 + * see AUTHORS for the list of contributors
16.7 + *
16.8 + * This program is free software: you can redistribute it and/or modify
16.9 + * it under the terms of the GNU General Public License as published by
16.10 + * the Free Software Foundation, either version 3 of the License, or
16.11 + * (at your option) any later version.
16.12 + *
16.13 + * This program is distributed in the hope that it will be useful,
16.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
16.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16.16 + * GNU General Public License for more details.
16.17 + *
16.18 + * You should have received a copy of the GNU General Public License
16.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
16.20 + */
16.21 +
16.22 +package com.so.news.command;
16.23 +
16.24 +import java.io.IOException;
16.25 +import java.util.ArrayList;
16.26 +import com.so.news.NNTPConnection;
16.27 +import com.so.news.storage.Group;
16.28 +
16.29 +/**
16.30 + * Class handling the NEWGROUPS command.
16.31 + * @author Christian Lins
16.32 + * @author Dennis Schwerdel
16.33 + */
16.34 +public class NewGroupsCommand extends Command
16.35 +{
16.36 + public NewGroupsCommand(NNTPConnection conn)
16.37 + {
16.38 + super(conn);
16.39 + }
16.40 +
16.41 + public boolean process(String[] command) throws IOException
16.42 + {
16.43 + String commandName = command[0];
16.44 + if (!commandName.equalsIgnoreCase("NEWGROUPS"))
16.45 + return false;
16.46 + if (command.length != 3)
16.47 + return false;
16.48 + // untested, not RFC977 complient
16.49 + try
16.50 + {
16.51 + // Timestamp date = new Timestamp ( new SimpleDateFormat ("yyMMdd
16.52 + // HHmmss").parse(command[1] + " " + command[2] ).getTime()) ;
16.53 + printStatus(231, "list of new newsgroups follows");
16.54 + ArrayList<Group> list = Group.getAll();// (date) ;
16.55 + for (Group g : list)
16.56 + {
16.57 + printTextLine(g.getName() + " " + g.getLastArticle() + " "
16.58 + + g.getFirstArticle() + " y");
16.59 + }
16.60 + println(".");
16.61 + flush();
16.62 + return true;
16.63 + }
16.64 + catch (Exception e)
16.65 + {
16.66 + printStatus(511, "listing failed - invalid date format");
16.67 + return true;
16.68 + }
16.69 + }
16.70 +
16.71 +}
17.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
17.2 +++ b/trunk/com/so/news/command/NextCommand.java Tue Jan 20 10:21:03 2009 +0100
17.3 @@ -0,0 +1,82 @@
17.4 +/*
17.5 + * StarOffice News Server
17.6 + * see AUTHORS for the list of contributors
17.7 + *
17.8 + * This program is free software: you can redistribute it and/or modify
17.9 + * it under the terms of the GNU General Public License as published by
17.10 + * the Free Software Foundation, either version 3 of the License, or
17.11 + * (at your option) any later version.
17.12 + *
17.13 + * This program is distributed in the hope that it will be useful,
17.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
17.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17.16 + * GNU General Public License for more details.
17.17 + *
17.18 + * You should have received a copy of the GNU General Public License
17.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
17.20 + */
17.21 +
17.22 +package com.so.news.command;
17.23 +
17.24 +import java.io.IOException;
17.25 +import com.so.news.NNTPConnection;
17.26 +import com.so.news.storage.Article;
17.27 +import com.so.news.storage.Group;
17.28 +
17.29 +/**
17.30 + * Class handling the NEXT and LAST command.
17.31 + * @author Christian Lins
17.32 + * @author Dennis Schwerdel
17.33 + */
17.34 +public class NextCommand extends Command
17.35 +{
17.36 + public NextCommand(NNTPConnection conn)
17.37 + {
17.38 + super(conn);
17.39 + }
17.40 +
17.41 + public boolean process(String[] command) throws IOException
17.42 + {
17.43 + String commandName = command[0];
17.44 + if (!(commandName.equalsIgnoreCase("NEXT") || commandName
17.45 + .equalsIgnoreCase("LAST")))
17.46 + return false;
17.47 + // untested, RFC977 complient
17.48 + Article currA = getCurrentArticle();
17.49 + Group currG = getCurrentGroup();
17.50 + if (currA == null)
17.51 + {
17.52 + printStatus(420, "no current article has been selected");
17.53 + return true;
17.54 + }
17.55 + if (currG == null)
17.56 + {
17.57 + printStatus(412, "no newsgroup selected");
17.58 + return true;
17.59 + }
17.60 + Article article;
17.61 + if (commandName.equalsIgnoreCase("NEXT"))
17.62 + {
17.63 + article = currA.nextArticleInGroup();
17.64 + if (article == null)
17.65 + {
17.66 + printStatus(421, "no next article in this group");
17.67 + return true;
17.68 + }
17.69 + }
17.70 + else
17.71 + {
17.72 + article = currA.prevArticleInGroup();
17.73 + if (article == null)
17.74 + {
17.75 + printStatus(422, "no previous article in this group");
17.76 + return true;
17.77 + }
17.78 + }
17.79 + setCurrentArticle(article);
17.80 + printStatus(223, article.getNumberInGroup() + " " + article.getMessageID()
17.81 + + " article retrieved - request text separately");
17.82 + return true;
17.83 + }
17.84 +
17.85 +}
18.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
18.2 +++ b/trunk/com/so/news/command/OverCommand.java Tue Jan 20 10:21:03 2009 +0100
18.3 @@ -0,0 +1,183 @@
18.4 +/*
18.5 + * StarOffice News Server
18.6 + * see AUTHORS for the list of contributors
18.7 + *
18.8 + * This program is free software: you can redistribute it and/or modify
18.9 + * it under the terms of the GNU General Public License as published by
18.10 + * the Free Software Foundation, either version 3 of the License, or
18.11 + * (at your option) any later version.
18.12 + *
18.13 + * This program is distributed in the hope that it will be useful,
18.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
18.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18.16 + * GNU General Public License for more details.
18.17 + *
18.18 + * You should have received a copy of the GNU General Public License
18.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
18.20 + */
18.21 +
18.22 +package com.so.news.command;
18.23 +
18.24 +import java.text.SimpleDateFormat;
18.25 +import java.util.Locale;
18.26 +
18.27 +import com.so.news.Debug;
18.28 +import com.so.news.NNTPConnection;
18.29 +import com.so.news.storage.Article;
18.30 +
18.31 +/**
18.32 + * Class handling the OVER/XOVER command.
18.33 + *
18.34 + * Description of the XOVER command:
18.35 + *
18.36 + * XOVER [range]
18.37 + *
18.38 + * The XOVER command returns information from the overview
18.39 + * database for the article(s) specified.
18.40 + *
18.41 + * The optional range argument may be any of the following:
18.42 + * an article number
18.43 + * an article number followed by a dash to indicate
18.44 + * all following
18.45 + * an article number followed by a dash followed by
18.46 + * another article number
18.47 + *
18.48 + * If no argument is specified, then information from the
18.49 + * current article is displayed. Successful responses start
18.50 + * with a 224 response followed by the overview information
18.51 + * for all matched messages. Once the output is complete, a
18.52 + * period is sent on a line by itself. If no argument is
18.53 + * specified, the information for the current article is
18.54 + * returned. A news group must have been selected earlier,
18.55 + * else a 412 error response is returned. If no articles are
18.56 + * in the range specified, a 420 error response is returned
18.57 + * by the server. A 502 response will be returned if the
18.58 + * client only has permission to transfer articles.
18.59 + *
18.60 + * Each line of output will be formatted with the article number,
18.61 + * followed by each of the headers in the overview database or the
18.62 + * article itself (when the data is not available in the overview
18.63 + * database) for that article separated by a tab character. The
18.64 + * sequence of fields must be in this order: subject, author,
18.65 + * date, message-id, references, byte count, and line count. Other
18.66 + * optional fields may follow line count. Other optional fields may
18.67 + * follow line count. These fields are specified by examining the
18.68 + * response to the LIST OVERVIEW.FMT command. Where no data exists,
18.69 + * a null field must be provided (i.e. the output will have two tab
18.70 + * characters adjacent to each other). Servers should not output
18.71 + * fields for articles that have been removed since the XOVER database
18.72 + * was created.
18.73 + *
18.74 + * The LIST OVERVIEW.FMT command should be implemented if XOVER
18.75 + * is implemented. A client can use LIST OVERVIEW.FMT to determine
18.76 + * what optional fields and in which order all fields will be
18.77 + * supplied by the XOVER command.
18.78 + *
18.79 + * Note that any tab and end-of-line characters in any header
18.80 + * data that is returned will be converted to a space character.
18.81 + *
18.82 + * Responses:
18.83 + *
18.84 + * 224 Overview information follows
18.85 + * 412 No news group current selected
18.86 + * 420 No article(s) selected
18.87 + * 502 no permission
18.88 + *
18.89 + * @author Christian Lins
18.90 + */
18.91 +public class OverCommand extends Command
18.92 +{
18.93 + public OverCommand(NNTPConnection conn)
18.94 + {
18.95 + super(conn);
18.96 + }
18.97 +
18.98 + public boolean process(String[] command)
18.99 + throws Exception
18.100 + {
18.101 + if(getCurrentGroup() == null)
18.102 + {
18.103 + printStatus(412, "No news group current selected");
18.104 + return false;
18.105 + }
18.106 +
18.107 + // If no parameter was specified, show information about
18.108 + // the currently selected article(s)
18.109 + if(command.length == 1)
18.110 + {
18.111 + Article art = getCurrentArticle();
18.112 + if(art == null)
18.113 + {
18.114 + printStatus(420, "No article(s) selected");
18.115 + return false;
18.116 + }
18.117 +
18.118 + String o = buildOverview(art, -1);
18.119 + printText(o);
18.120 + }
18.121 + // otherwise print information about the specified range
18.122 + else
18.123 + {
18.124 + int artStart = -1;
18.125 + int artEnd = -1;
18.126 + String[] nums = command[1].split("-");
18.127 + if(nums.length > 1)
18.128 + {
18.129 + try
18.130 + {
18.131 + artStart = Integer.parseInt(nums[0]);
18.132 + }
18.133 + catch(Exception e)
18.134 + {
18.135 + artStart = Integer.parseInt(command[1]);
18.136 + }
18.137 + try
18.138 + {
18.139 + artEnd = Integer.parseInt(nums[1]);
18.140 + }
18.141 + catch(Exception e) {}
18.142 + }
18.143 +
18.144 + printStatus(224, "Overview information follows");
18.145 + for(int n = artStart; n <= artEnd; n++)
18.146 + {
18.147 + Article art = Article.getByNumberInGroup(getCurrentGroup(), n);
18.148 + if(art == null)
18.149 + {
18.150 + Debug.getInstance().log("Article (gid=" + getCurrentGroup() + ", art=" + n + " is null!");
18.151 + }
18.152 + else
18.153 + {
18.154 + printTextPart(buildOverview(art, n) + NEWLINE);
18.155 + }
18.156 + }
18.157 + println(".");
18.158 + flush();
18.159 + }
18.160 +
18.161 + return true;
18.162 + }
18.163 +
18.164 + private String buildOverview(Article art, int nr)
18.165 + {
18.166 + SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
18.167 + StringBuilder overview = new StringBuilder();
18.168 + overview.append(nr);
18.169 + overview.append('\t');
18.170 + overview.append(art.getHeader().get("Subject"));
18.171 + overview.append('\t');
18.172 + overview.append(art.getHeader().get("From"));
18.173 + overview.append('\t');
18.174 + overview.append(sdf.format(art.getDate()));
18.175 + overview.append('\t');
18.176 + overview.append(art.getHeader().get("Message-ID"));
18.177 + overview.append('\t');
18.178 + overview.append(art.getHeader().get("References"));
18.179 + overview.append('\t');
18.180 + overview.append(art.getHeader().get("Bytes"));
18.181 + overview.append('\t');
18.182 + overview.append(art.getHeader().get("Lines"));
18.183 +
18.184 + return overview.toString();
18.185 + }
18.186 +}
19.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
19.2 +++ b/trunk/com/so/news/command/PostCommand.java Tue Jan 20 10:21:03 2009 +0100
19.3 @@ -0,0 +1,166 @@
19.4 +/*
19.5 + * StarOffice News Server
19.6 + * see AUTHORS for the list of contributors
19.7 + *
19.8 + * This program is free software: you can redistribute it and/or modify
19.9 + * it under the terms of the GNU General Public License as published by
19.10 + * the Free Software Foundation, either version 3 of the License, or
19.11 + * (at your option) any later version.
19.12 + *
19.13 + * This program is distributed in the hope that it will be useful,
19.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
19.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19.16 + * GNU General Public License for more details.
19.17 + *
19.18 + * You should have received a copy of the GNU General Public License
19.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
19.20 + */
19.21 +
19.22 +package com.so.news.command;
19.23 +
19.24 +import java.io.IOException;
19.25 +import java.sql.SQLException;
19.26 +import java.util.Date;
19.27 +import java.text.SimpleDateFormat;
19.28 +import java.util.HashMap;
19.29 +import java.util.Locale;
19.30 +
19.31 +import com.so.news.Config;
19.32 +import com.so.news.Debug;
19.33 +import com.so.news.NNTPConnection;
19.34 +import com.so.news.storage.Article;
19.35 +import com.so.news.storage.Database;
19.36 +
19.37 +/**
19.38 + * Contains the code for the POST command.
19.39 + * @author Christian Lins
19.40 + * @author Dennis Schwerdel
19.41 + */
19.42 +public class PostCommand extends Command
19.43 +{
19.44 + public PostCommand(NNTPConnection conn)
19.45 + {
19.46 + super(conn);
19.47 + }
19.48 +
19.49 + public boolean process(String[] command) throws IOException
19.50 + {
19.51 + printStatus(340, "send article to be posted. End with <CR-LF>.<CR-LF>");
19.52 +
19.53 + // some initialization
19.54 + Article article = new Article();
19.55 + int lineCount = 0;
19.56 + long bodySize = 0;
19.57 + long maxBodySize = Config.getInstance().get("n3tpd.article.maxsize", 1024) * 1024; // Size in bytes
19.58 +
19.59 + // begin with a stringbuilder body
19.60 + StringBuilder body = new StringBuilder();
19.61 + HashMap<String, String> header = new HashMap<String, String>();
19.62 +
19.63 + boolean isHeader = true; // are we in the header part
19.64 +
19.65 + String line = readTextLine();
19.66 + while(line != null)
19.67 + {
19.68 + bodySize += line.length();
19.69 + if(bodySize > maxBodySize)
19.70 + {
19.71 + printStatus(500, "article is too long");
19.72 + return false;
19.73 + }
19.74 +
19.75 + if(!isHeader)
19.76 + { // body
19.77 + if(line.trim().equals("."))
19.78 + break;
19.79 +
19.80 + bodySize += line.length() + 1;
19.81 + lineCount++;
19.82 + body.append(line + NEWLINE);
19.83 + }
19.84 +
19.85 + if(line.equals(""))
19.86 + {
19.87 + isHeader = false; // we finally met the blank line
19.88 + // separating headers from body
19.89 + }
19.90 +
19.91 + if(isHeader)
19.92 + { // header
19.93 + // split name and value and add the header to the map
19.94 + int colon = line.indexOf(':');
19.95 + String fieldName = line.substring(0, colon).trim();
19.96 + String fieldValue = line.substring(colon + 1).trim();
19.97 + header.put(fieldName, fieldValue);
19.98 + }
19.99 + line = readTextLine(); // read a new line
19.100 + } // end of input reading
19.101 +
19.102 + article.setBody(body.toString()); // set the article body
19.103 + article.setHeader(header); // add the header entries for the article
19.104 +
19.105 + // Read the date header and fall back to the current date if it is not set
19.106 + try
19.107 + {
19.108 + SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
19.109 + String date = header.get("DATE");
19.110 + if(date == null)
19.111 + article.setDate(new Date());
19.112 + else
19.113 + article.setDate(new Date(sdf.parse(date).getTime())) ;
19.114 + }
19.115 + catch (Exception e)
19.116 + {
19.117 + e.printStackTrace(Debug.getInstance().getStream());
19.118 + printStatus(541, "posting failed - invalid date format");
19.119 + return true;
19.120 + }
19.121 +
19.122 + // check for a cancel command
19.123 + if ( header.containsKey("Control") )
19.124 + {
19.125 + String[] control = header.get("Control").split(" ") ;
19.126 + if ( control.length >= 2 && control[0].equalsIgnoreCase("cancel") )
19.127 + {
19.128 + // this article is a cancel-article, try to delete the old article
19.129 + try
19.130 + {
19.131 + Article.getByMessageID(control[1]).delete();
19.132 + printStatus(240, "article posted ok - original article canceled"); // quite
19.133 + return true; // quit, do not actually post this article since it
19.134 + }
19.135 + catch (Exception e)
19.136 + {
19.137 + e.printStackTrace();
19.138 + printStatus(441, "posting failed - original posting not found");
19.139 + return true;
19.140 + }
19.141 + }
19.142 + }
19.143 +
19.144 + // set some headers
19.145 + header.put("Message-ID", article.getMessageID());
19.146 + header.put("Lines", "" + lineCount);
19.147 + header.put("Bytes", "" + bodySize);
19.148 +
19.149 + // if needed, set an empty references header, that means this is
19.150 + // a initial posting
19.151 + if (!header.containsKey("References"))
19.152 + header.put("References", "");
19.153 +
19.154 + // try to create the article in the database
19.155 + try
19.156 + {
19.157 + Database.getInstance().addArticle(article);
19.158 + printStatus(240, "article posted ok");
19.159 + }
19.160 + catch(SQLException ex)
19.161 + {
19.162 + System.err.println(ex.getLocalizedMessage());
19.163 + ex.printStackTrace(Debug.getInstance().getStream());
19.164 + printStatus(500, "internal server error");
19.165 + }
19.166 +
19.167 + return true;
19.168 + }
19.169 +}
20.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
20.2 +++ b/trunk/com/so/news/io/Resource.java Tue Jan 20 10:21:03 2009 +0100
20.3 @@ -0,0 +1,123 @@
20.4 +/*
20.5 + * StarOffice News Server
20.6 + * see AUTHORS for the list of contributors
20.7 + *
20.8 + * This program is free software: you can redistribute it and/or modify
20.9 + * it under the terms of the GNU General Public License as published by
20.10 + * the Free Software Foundation, either version 3 of the License, or
20.11 + * (at your option) any later version.
20.12 + *
20.13 + * This program is distributed in the hope that it will be useful,
20.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
20.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20.16 + * GNU General Public License for more details.
20.17 + *
20.18 + * You should have received a copy of the GNU General Public License
20.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
20.20 + */
20.21 +
20.22 +package com.so.news.io;
20.23 +
20.24 +import java.io.BufferedReader;
20.25 +import java.io.File;
20.26 +import java.io.FileInputStream;
20.27 +import java.io.IOException;
20.28 +import java.io.InputStream;
20.29 +import java.io.InputStreamReader;
20.30 +import java.net.URL;
20.31 +import java.nio.charset.Charset;
20.32 +
20.33 +/**
20.34 + * Provides method for loading of resources.
20.35 + * @author Christian Lins
20.36 + */
20.37 +public class Resource
20.38 +{
20.39 + /**
20.40 + * Loads a file as array of byte. As the file is completely loaded into
20.41 + * memory this method should only be used with small files.
20.42 + * @param file
20.43 + * @return
20.44 + */
20.45 + public static byte[] getBytes(File file)
20.46 + {
20.47 + try
20.48 + {
20.49 + FileInputStream in = new FileInputStream(file);
20.50 + byte[] buffer = new byte[(int)file.length()];
20.51 +
20.52 + in.read(buffer);
20.53 +
20.54 + return buffer;
20.55 + }
20.56 + catch(IOException ex)
20.57 + {
20.58 + System.err.println(ex.getLocalizedMessage());
20.59 + return null;
20.60 + }
20.61 + }
20.62 +
20.63 + /**
20.64 + * Loads a resource and returns it as URL reference.
20.65 + * The Resource's classloader is used to load the resource, not
20.66 + * the System's ClassLoader so it may be safe to use this method
20.67 + * in a sandboxed environment.
20.68 + * @return
20.69 + */
20.70 + public static URL getAsURL(String name)
20.71 + {
20.72 + return Resource.class.getClassLoader().getResource(name);
20.73 + }
20.74 +
20.75 + /**
20.76 + * Loads a resource and returns an InputStream to it.
20.77 + * @param name
20.78 + * @return
20.79 + */
20.80 + public static InputStream getAsStream(String name)
20.81 + {
20.82 + try
20.83 + {
20.84 + URL url = getAsURL(name);
20.85 + return url.openStream();
20.86 + }
20.87 + catch(IOException e)
20.88 + {
20.89 + e.printStackTrace();
20.90 + return null;
20.91 + }
20.92 + }
20.93 +
20.94 + /**
20.95 + * Loads a plain text resource.
20.96 + * @param withNewline If false all newlines are removed from the
20.97 + * return String
20.98 + */
20.99 + public static String getAsString(String name, boolean withNewline)
20.100 + {
20.101 + try
20.102 + {
20.103 + BufferedReader in = new BufferedReader(
20.104 + new InputStreamReader(getAsStream(name), Charset.forName("UTF-8")));
20.105 + StringBuffer buf = new StringBuffer();
20.106 +
20.107 + for(;;)
20.108 + {
20.109 + String line = in.readLine();
20.110 + if(line == null)
20.111 + break;
20.112 +
20.113 + buf.append(line);
20.114 + if(withNewline)
20.115 + buf.append('\n');
20.116 + }
20.117 +
20.118 + return buf.toString();
20.119 + }
20.120 + catch(Exception e)
20.121 + {
20.122 + e.printStackTrace();
20.123 + return null;
20.124 + }
20.125 + }
20.126 +}
21.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
21.2 +++ b/trunk/com/so/news/storage/Article.java Tue Jan 20 10:21:03 2009 +0100
21.3 @@ -0,0 +1,307 @@
21.4 +/*
21.5 + * StarOffice News Server
21.6 + * see AUTHORS for the list of contributors
21.7 + *
21.8 + * This program is free software: you can redistribute it and/or modify
21.9 + * it under the terms of the GNU General Public License as published by
21.10 + * the Free Software Foundation, either version 3 of the License, or
21.11 + * (at your option) any later version.
21.12 + *
21.13 + * This program is distributed in the hope that it will be useful,
21.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
21.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21.16 + * GNU General Public License for more details.
21.17 + *
21.18 + * You should have received a copy of the GNU General Public License
21.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
21.20 + */
21.21 +
21.22 +package com.so.news.storage;
21.23 +
21.24 +import java.sql.ResultSet;
21.25 +import java.sql.SQLException;
21.26 +import java.util.Date;
21.27 +import java.util.HashMap;
21.28 +import java.util.Map;
21.29 +import java.util.Map.Entry;
21.30 +import java.util.UUID;
21.31 +
21.32 +import com.so.news.Config;
21.33 +import com.so.news.Debug;
21.34 +
21.35 +/**
21.36 + * Represents a newsgroup article.
21.37 + * @author Christian Lins
21.38 + * @author Denis Schwerdel
21.39 + */
21.40 +public class Article
21.41 +{
21.42 + /**
21.43 + * Loads the Article identified by the given ID from the Database.
21.44 + * @param messageID
21.45 + * @return null if Article is not found or if an error occurred.
21.46 + */
21.47 + public static Article getByMessageID(String messageID)
21.48 + {
21.49 + try
21.50 + {
21.51 + return Database.getInstance().getArticle(messageID);
21.52 + }
21.53 + catch(SQLException ex)
21.54 + {
21.55 + ex.printStackTrace(Debug.getInstance().getStream());
21.56 + return null;
21.57 + }
21.58 + }
21.59 +
21.60 + public static Article getByNumberInGroup(Group group, int number)
21.61 + throws SQLException
21.62 + {
21.63 + long gid = group.getID();
21.64 + return Database.getInstance().getArticle(gid, number); // Is number her correct?
21.65 + }
21.66 +
21.67 + private String body = "";
21.68 + private long groupID = -1;
21.69 + private Map<String, String> header = new HashMap<String, String>();
21.70 + private int numberInGroup = -1;
21.71 + private String msgID = null;
21.72 +
21.73 + /**
21.74 + * Default constructor.
21.75 + */
21.76 + public Article()
21.77 + {
21.78 + }
21.79 +
21.80 + /**
21.81 + * Creates a new Article object using the date from the given
21.82 + * ResultSet. It is expected that ResultSet.next() was already
21.83 + * called by the Database class.
21.84 + * This construction has only package visibility.
21.85 + * @param rs
21.86 + */
21.87 + Article(ResultSet rs)
21.88 + throws SQLException
21.89 + {
21.90 + this.body = rs.getString("body");
21.91 + this.msgID = rs.getString("message_id");
21.92 +
21.93 + // Parse the header
21.94 + parseHeader(rs.getString("header"));
21.95 + }
21.96 +
21.97 + /**
21.98 + * Parses the header fields and puts them into a map for faster access.
21.99 + * TODO: There could be fields that go over more than one line, some
21.100 + * bad clients do create them.
21.101 + * @param hsrc
21.102 + */
21.103 + private void parseHeader(String hsrc)
21.104 + {
21.105 + String[] lines = hsrc.split("\n");
21.106 +
21.107 + for(String line : lines)
21.108 + {
21.109 + String[] kv = line.split(":");
21.110 + if(kv.length < 2)
21.111 + {
21.112 + Debug.getInstance().log("Invalid header field: " + line);
21.113 + continue;
21.114 + }
21.115 + else
21.116 + {
21.117 + // Set value in the header hash map
21.118 + String value = kv[1];
21.119 + for(int n = 2; n < kv.length; n++)
21.120 + value += ":" + kv[n];
21.121 + this.header.put(kv[0], value);
21.122 + }
21.123 + }
21.124 + }
21.125 +
21.126 + /**
21.127 + * Returnes the next Article in the group of this Article.
21.128 + * @return
21.129 + */
21.130 + public Article nextArticleInGroup()
21.131 + {
21.132 + return null;
21.133 + }
21.134 +
21.135 + /**
21.136 + * Returns the previous Article in the group of this Article.
21.137 + * @return
21.138 + */
21.139 + public Article prevArticleInGroup()
21.140 + {
21.141 + return null;
21.142 + }
21.143 +
21.144 + /**
21.145 + * Generates a message id for this article and sets it into
21.146 + * the header HashMap.
21.147 + */
21.148 + private String generateMessageID()
21.149 + {
21.150 + this.msgID = "<" + UUID.randomUUID() + "@"
21.151 + + Config.getInstance().get("n3tpd.hostname", "localhost") + ">";
21.152 +
21.153 + this.header.put("Message-ID", msgID);
21.154 +
21.155 + return msgID;
21.156 + }
21.157 +
21.158 + /**
21.159 + * Tries to delete this article.
21.160 + * @return false if the article could not be deleted, otherwise true
21.161 + */
21.162 + public boolean delete()
21.163 + {
21.164 + return false;
21.165 + }
21.166 +
21.167 + /**
21.168 + * Checks if all necessary header fields are within this header.
21.169 + */
21.170 + private void validateHeader()
21.171 + {
21.172 + // Forces a MessageID creation if not existing
21.173 + getMessageID();
21.174 +
21.175 + // Check if the references are correct...
21.176 + String rep = header.get("In-Reply-To");
21.177 + if(rep == null) // Some clients use only references instead of In-Reply-To
21.178 + return; //rep = header.get("References");
21.179 +
21.180 + String ref = getMessageID();
21.181 +
21.182 + if(rep != null && !rep.equals(""))
21.183 + {
21.184 + Article art = null; //TODO // getByMessageID(rep, articleDir);
21.185 + if(art != null)
21.186 + {
21.187 + ref = art.header.get("References") + " " + rep;
21.188 + }
21.189 + }
21.190 + header.put("References", ref);
21.191 + }
21.192 +
21.193 + /**
21.194 + * Returns the body string.
21.195 + */
21.196 + public String getBody()
21.197 + {
21.198 + return body;
21.199 + }
21.200 +
21.201 + /**
21.202 + * @return Numerical ID of the associated Group.
21.203 + */
21.204 + long getGroupID()
21.205 + {
21.206 + if(groupID == -1) // If the GroupID was not determined yet
21.207 + {
21.208 + // Determining GroupID
21.209 + String newsgroups = this.header.get("Newsgroups");
21.210 + if(newsgroups != null)
21.211 + {
21.212 + String[] newsgroup = newsgroups.split(",");
21.213 + // Crossposting is not supported
21.214 + try
21.215 + {
21.216 + Group group;
21.217 + if(newsgroup.length > 0)
21.218 + group = Database.getInstance().getGroup(newsgroup[0].trim());
21.219 + else
21.220 + group = Database.getInstance().getGroup(newsgroups.trim());
21.221 + // TODO: What to do if Group does not exist?
21.222 + this.groupID = group.getID();
21.223 + }
21.224 + catch(SQLException ex)
21.225 + {
21.226 + ex.printStackTrace(Debug.getInstance().getStream());
21.227 + System.err.println(ex.getLocalizedMessage());
21.228 + }
21.229 + }
21.230 + else
21.231 + System.err.println("Should never happen: Article::getGroupID");
21.232 + }
21.233 + return this.groupID;
21.234 + }
21.235 +
21.236 + public void setBody(String body)
21.237 + {
21.238 + this.body = body;
21.239 + }
21.240 +
21.241 + public int getNumberInGroup()
21.242 + {
21.243 + return this.numberInGroup;
21.244 + }
21.245 +
21.246 + public void setHeader(HashMap<String, String> header)
21.247 + {
21.248 + this.header = header;
21.249 + }
21.250 +
21.251 + public void setNumberInGroup(int id)
21.252 + {
21.253 + this.numberInGroup = id;
21.254 + }
21.255 +
21.256 + public String getMessageID()
21.257 + {
21.258 + if(msgID == null)
21.259 + msgID = generateMessageID();
21.260 + return msgID;
21.261 + }
21.262 +
21.263 + /**
21.264 + * @return Header source code of this Article.
21.265 + */
21.266 + public String getHeaderSource()
21.267 + {
21.268 + StringBuffer buf = new StringBuffer();
21.269 +
21.270 + for(Entry<String, String> entry : this.header.entrySet())
21.271 + {
21.272 + buf.append(entry.getKey());
21.273 + buf.append(":");
21.274 + buf.append(entry.getValue());
21.275 + buf.append("\n");
21.276 + }
21.277 +
21.278 + return buf.toString();
21.279 + }
21.280 +
21.281 + public Map<String, String> getHeader()
21.282 + {
21.283 + return this.header;
21.284 + }
21.285 +
21.286 + public Date getDate()
21.287 + {
21.288 + try
21.289 + {
21.290 + String date = this.header.get("Date");
21.291 + return new Date(Date.parse(date));
21.292 + }
21.293 + catch(Exception e)
21.294 + {
21.295 + e.printStackTrace(Debug.getInstance().getStream());
21.296 + return null;
21.297 + }
21.298 + }
21.299 +
21.300 + public void setDate(Date date)
21.301 + {
21.302 + this.header.put("Date", date.toString());
21.303 + }
21.304 +
21.305 + @Override
21.306 + public String toString()
21.307 + {
21.308 + return getMessageID();
21.309 + }
21.310 +}
22.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
22.2 +++ b/trunk/com/so/news/storage/Database.java Tue Jan 20 10:21:03 2009 +0100
22.3 @@ -0,0 +1,327 @@
22.4 +/*
22.5 + * StarOffice News Server
22.6 + * see AUTHORS for the list of contributors
22.7 + *
22.8 + * This program is free software: you can redistribute it and/or modify
22.9 + * it under the terms of the GNU General Public License as published by
22.10 + * the Free Software Foundation, either version 3 of the License, or
22.11 + * (at your option) any later version.
22.12 + *
22.13 + * This program is distributed in the hope that it will be useful,
22.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
22.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22.16 + * GNU General Public License for more details.
22.17 + *
22.18 + * You should have received a copy of the GNU General Public License
22.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
22.20 + */
22.21 +
22.22 +package com.so.news.storage;
22.23 +
22.24 +import java.sql.Connection;
22.25 +import java.sql.DriverManager;
22.26 +import java.sql.ResultSet;
22.27 +import java.sql.SQLException;
22.28 +import java.sql.Statement;
22.29 +
22.30 +import java.util.zip.CRC32;
22.31 +import com.so.news.Config;
22.32 +import com.so.news.util.StringTemplate;
22.33 +
22.34 +/**
22.35 + * Database abstraction class.
22.36 + * @author Christian Lins (christian.lins@web.de)
22.37 + */
22.38 +public class Database
22.39 +{
22.40 + private static Database instance = null;
22.41 +
22.42 + /**
22.43 + * Initializes the Database subsystem, e.g. loading a JDBC driver and
22.44 + * connection to the Database Managment System.
22.45 + * This method is called when the daemon starts up or at the first
22.46 + * call to Database.getInstance().
22.47 + * @throws java.lang.Exception
22.48 + */
22.49 + public static void arise()
22.50 + throws Exception
22.51 + {
22.52 + // Tries to load the Database driver and establish a connection.
22.53 + if(instance == null)
22.54 + instance = new Database();
22.55 + }
22.56 +
22.57 + /**
22.58 + * @return Instance of the current Database backend. Returns null if an error
22.59 + * has occurred.
22.60 + */
22.61 + public static Database getInstance()
22.62 + {
22.63 + try
22.64 + {
22.65 + arise();
22.66 + return instance;
22.67 + }
22.68 + catch(Exception ex)
22.69 + {
22.70 + ex.printStackTrace();
22.71 + return null;
22.72 + }
22.73 + }
22.74 +
22.75 + private Connection conn = null;
22.76 +
22.77 + /**
22.78 + * Private constructor.
22.79 + * @throws java.lang.Exception
22.80 + */
22.81 + private Database()
22.82 + throws Exception
22.83 + {
22.84 + Class.forName(
22.85 + Config.getInstance().get("n3tpd.storage.dbmsdriver", ""));
22.86 + this.conn = DriverManager.getConnection(
22.87 + Config.getInstance().get("n3tpd.storage.database", ""),
22.88 + Config.getInstance().get("n3tpd.storage.user", "n3tpd_user"),
22.89 + Config.getInstance().get("n3tpd.storage.password", ""));
22.90 + this.conn.setAutoCommit(false);
22.91 + }
22.92 +
22.93 + /**
22.94 + * Adds an article to the database.
22.95 + * @param article
22.96 + * @return
22.97 + * @throws java.sql.SQLException
22.98 + */
22.99 + public boolean addArticle(Article article)
22.100 + throws SQLException
22.101 + {
22.102 + Statement stmt = this.conn.createStatement();
22.103 +
22.104 + String sql0 = "START TRANSACTION";
22.105 + String sql1 = "INSERT INTO articles (message_id,header,body)" +
22.106 + "VALUES('%mid', '%header', '%body')";
22.107 + StringTemplate tmpl = new StringTemplate(sql1);
22.108 + tmpl.set("body", article.getBody());
22.109 + tmpl.set("mid", article.getMessageID());
22.110 + tmpl.set("header", article.getHeaderSource());
22.111 + sql1 = tmpl.toString();
22.112 +
22.113 + String sql2 = "COMMIT";
22.114 +
22.115 + // Add statements as batch
22.116 + stmt.addBatch(sql0);
22.117 + stmt.addBatch(sql1);
22.118 +
22.119 + // TODO: For each newsgroup add a reference
22.120 + String sql = "INSERT INTO postings (group_id, article_id, article_index)" +
22.121 + "VALUES (%gid, (SELECT article_id FROM articles WHERE message_id = '%mid')," +
22.122 + " %idx)";
22.123 +
22.124 + tmpl = new StringTemplate(sql);
22.125 + tmpl.set("gid", article.getGroupID());
22.126 + tmpl.set("mid", article.getMessageID());
22.127 + tmpl.set("idx", getMaxArticleIndex() + 1);
22.128 + stmt.addBatch(tmpl.toString());
22.129 +
22.130 + // Commit
22.131 + stmt.addBatch(sql2);
22.132 +
22.133 + // And execute the batch
22.134 + stmt.executeBatch();
22.135 +
22.136 + return true;
22.137 + }
22.138 +
22.139 + /**
22.140 + * Adds a group to the Database.
22.141 + * @param name
22.142 + * @throws java.sql.SQLException
22.143 + */
22.144 + public boolean addGroup(String name)
22.145 + throws SQLException
22.146 + {
22.147 + CRC32 crc = new CRC32();
22.148 + crc.update(name.getBytes());
22.149 +
22.150 + long id = crc.getValue();
22.151 +
22.152 + Statement stmt = conn.createStatement();
22.153 + return 1 == stmt.executeUpdate("INSERT INTO Groups (ID, Name) VALUES (" + id + ", '" + name + "')");
22.154 + }
22.155 +
22.156 + public void delete(Article article)
22.157 + {
22.158 +
22.159 + }
22.160 +
22.161 + public void delete(Group group)
22.162 + {
22.163 +
22.164 + }
22.165 +
22.166 + public Article getArticle(String messageID)
22.167 + throws SQLException
22.168 + {
22.169 + Statement stmt = this.conn.createStatement();
22.170 + ResultSet rs =
22.171 + stmt.executeQuery("SELECT * FROM articles WHERE message_id = '" + messageID + "'");
22.172 +
22.173 + return new Article(rs);
22.174 + }
22.175 +
22.176 + public Article getArticle(long gid, long article_id)
22.177 + throws SQLException
22.178 + {
22.179 + Statement stmt = this.conn.createStatement();
22.180 + String sql = "SELECT * FROM articles WHERE article_id = " +
22.181 + "(SELECT article_id FROM postings WHERE " +
22.182 + "group_id = " + gid + " AND article_id = " + article_id +")";
22.183 + ResultSet rs =
22.184 + stmt.executeQuery(sql);
22.185 +
22.186 + if(rs.next())
22.187 + return new Article(rs);
22.188 + else
22.189 + return null;
22.190 + }
22.191 +
22.192 + public ResultSet getArticles()
22.193 + throws SQLException
22.194 + {
22.195 + Statement stmt = conn.createStatement();
22.196 + return stmt.executeQuery("SELECT * FROM articles");
22.197 + }
22.198 +
22.199 + /**
22.200 + * Reads all Groups from the Database.
22.201 + * @return
22.202 + * @throws java.sql.SQLException
22.203 + */
22.204 + public ResultSet getGroups()
22.205 + throws SQLException
22.206 + {
22.207 + Statement stmt = conn.createStatement();
22.208 + ResultSet rs = stmt.executeQuery("SELECT * FROM groups");
22.209 +
22.210 + return rs;
22.211 + }
22.212 +
22.213 + /**
22.214 + * Returns the Group that is identified by the name.
22.215 + * @param name
22.216 + * @return
22.217 + * @throws java.sql.SQLException
22.218 + */
22.219 + public Group getGroup(String name)
22.220 + throws SQLException
22.221 + {
22.222 + Statement stmt = this.conn.createStatement();
22.223 + String sql = "SELECT group_id FROM groups WHERE Name = '%name'";
22.224 + StringTemplate tmpl = new StringTemplate(sql);
22.225 + tmpl.set("name", name);
22.226 +
22.227 + ResultSet rs = stmt.executeQuery(tmpl.toString());
22.228 +
22.229 + if(!rs.next())
22.230 + return null;
22.231 + else
22.232 + {
22.233 + long id = rs.getLong("group_id");
22.234 + return new Group(name, id);
22.235 + }
22.236 + }
22.237 +
22.238 + public int getMaxArticleIndex()
22.239 + throws SQLException
22.240 + {
22.241 + Statement stmt = conn.createStatement();
22.242 + ResultSet rs = stmt.executeQuery(
22.243 + "SELECT Max(article_index) FROM postings");
22.244 +
22.245 + if(!rs.next())
22.246 + return 0;
22.247 + else
22.248 + return rs.getInt(1);
22.249 + }
22.250 +
22.251 + public int getLastArticleNumber(Group group)
22.252 + throws SQLException
22.253 + {
22.254 + Statement stmt = conn.createStatement();
22.255 + ResultSet rs = stmt.executeQuery(
22.256 + "SELECT Max(article_index) FROM postings WHERE group_id = " + group.getID());
22.257 +
22.258 + if(!rs.next())
22.259 + return 0;
22.260 + else
22.261 + return rs.getInt(1);
22.262 + }
22.263 +
22.264 + public int getFirstArticleNumber(Group group)
22.265 + throws SQLException
22.266 + {
22.267 + Statement stmt = conn.createStatement();
22.268 + ResultSet rs = stmt.executeQuery(
22.269 + "SELECT Min(article_index) FROM postings WHERE group_id = " + group.getID());
22.270 +
22.271 + if(!rs.next())
22.272 + return 0;
22.273 + else
22.274 + return rs.getInt(1);
22.275 + }
22.276 +
22.277 + /**
22.278 + * Returns a group name identified by the given id.
22.279 + * @param id
22.280 + * @return
22.281 + * @throws java.sql.SQLException
22.282 + */
22.283 + public String getGroup(int id)
22.284 + throws SQLException
22.285 + {
22.286 + Statement stmt = conn.createStatement();
22.287 + ResultSet rs = stmt.executeQuery(
22.288 + "SELECT name FROM groups WHERE group_id = '" + id + "'");
22.289 +
22.290 + if(rs.next())
22.291 + {
22.292 + return rs.getString(1);
22.293 + }
22.294 + else
22.295 + return null;
22.296 + }
22.297 +
22.298 + public Article getOldestArticle()
22.299 + throws SQLException
22.300 + {
22.301 + Statement stmt = conn.createStatement();
22.302 + ResultSet rs =
22.303 + stmt.executeQuery("SELECT * FROM Articles WHERE Date = (SELECT Min(Date) FROM Articles)");
22.304 +
22.305 + if(rs.next())
22.306 + return new Article(rs);
22.307 + else
22.308 + return null;
22.309 + }
22.310 +
22.311 + /**
22.312 + * Checks if there is a group with the given name in the Database.
22.313 + * @param name
22.314 + * @return
22.315 + * @throws java.sql.SQLException
22.316 + */
22.317 + public boolean isGroupExisting(String name)
22.318 + throws SQLException
22.319 + {
22.320 + Statement stmt = this.conn.createStatement();
22.321 + ResultSet rs = stmt.executeQuery("SELECT * FROM Groups WHERE Name = '" + name + "'");
22.322 +
22.323 + return rs.next();
22.324 + }
22.325 +
22.326 + public void updateArticle(Article article)
22.327 + {
22.328 +
22.329 + }
22.330 +}
23.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
23.2 +++ b/trunk/com/so/news/storage/Group.java Tue Jan 20 10:21:03 2009 +0100
23.3 @@ -0,0 +1,142 @@
23.4 +/*
23.5 + * StarOffice News Server
23.6 + * see AUTHORS for the list of contributors
23.7 + *
23.8 + * This program is free software: you can redistribute it and/or modify
23.9 + * it under the terms of the GNU General Public License as published by
23.10 + * the Free Software Foundation, either version 3 of the License, or
23.11 + * (at your option) any later version.
23.12 + *
23.13 + * This program is distributed in the hope that it will be useful,
23.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
23.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23.16 + * GNU General Public License for more details.
23.17 + *
23.18 + * You should have received a copy of the GNU General Public License
23.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
23.20 + */
23.21 +
23.22 +package com.so.news.storage;
23.23 +
23.24 +import java.sql.ResultSet;
23.25 +import java.sql.SQLException;
23.26 +import java.util.ArrayList;
23.27 +import java.util.List;
23.28 +import com.so.news.Debug;
23.29 +
23.30 +/**
23.31 + * Represents a logical Group within this newsserver.
23.32 + * @author Christian Lins
23.33 + */
23.34 +public class Group
23.35 +{
23.36 + private long id;
23.37 + private String name;
23.38 +
23.39 + /**
23.40 + * Private constructor.
23.41 + * @param name
23.42 + * @param id
23.43 + */
23.44 + Group(String name, long id)
23.45 + {
23.46 + this.id = id;
23.47 + this.name = name;
23.48 + }
23.49 +
23.50 + /**
23.51 + * Returns a Group identified by its full name.
23.52 + * @param name
23.53 + * @return
23.54 + */
23.55 + public static Group getByName(String name)
23.56 + {
23.57 + try
23.58 + {
23.59 + return Database.getInstance().getGroup(name);
23.60 + }
23.61 + catch(SQLException ex)
23.62 + {
23.63 + System.err.println(ex.getLocalizedMessage());
23.64 + ex.printStackTrace(Debug.getInstance().getStream());
23.65 + return null;
23.66 + }
23.67 + }
23.68 +
23.69 + /**
23.70 + * Returns a list of all groups this server handles.
23.71 + * @return
23.72 + */
23.73 + public static ArrayList<Group> getAll()
23.74 + {
23.75 + ArrayList<Group> buffer = new ArrayList<Group>();
23.76 +
23.77 + try
23.78 + {
23.79 + ResultSet rs = Database.getInstance().getGroups();
23.80 +
23.81 + while(rs.next())
23.82 + {
23.83 + String name = rs.getString("name");
23.84 + long id = rs.getLong("group_id");
23.85 +
23.86 + Group group = new Group(name, id);
23.87 + buffer.add(group);
23.88 + }
23.89 + }
23.90 + catch(SQLException ex)
23.91 + {
23.92 + ex.printStackTrace(Debug.getInstance().getStream());
23.93 + System.err.println(ex.getLocalizedMessage());
23.94 + }
23.95 +
23.96 + return buffer;
23.97 + }
23.98 +
23.99 + public List<Article> getAllArticles()
23.100 + throws SQLException
23.101 + {
23.102 + return getAllArticles(getFirstArticle(), getLastArticle());
23.103 + }
23.104 +
23.105 + public List<Article> getAllArticles(int first, int last)
23.106 + {
23.107 + return null;
23.108 + }
23.109 +
23.110 + public int getFirstArticle()
23.111 + throws SQLException
23.112 + {
23.113 + return Database.getInstance().getFirstArticleNumber(this);
23.114 + }
23.115 +
23.116 + public long getID()
23.117 + {
23.118 + return id;
23.119 + }
23.120 +
23.121 + public int getLastArticle()
23.122 + throws SQLException
23.123 + {
23.124 + return Database.getInstance().getLastArticleNumber(this);
23.125 + }
23.126 +
23.127 + public String getName()
23.128 + {
23.129 + return name;
23.130 + }
23.131 +
23.132 + public void setName(String name)
23.133 + {
23.134 + this.name = name;
23.135 + }
23.136 +
23.137 + public int getEstimatedArticleCount()
23.138 + throws SQLException
23.139 + {
23.140 + if (getLastArticle() < getFirstArticle())
23.141 + return 0;
23.142 + return getLastArticle() - getFirstArticle() + 1;
23.143 + }
23.144 +
23.145 +}
24.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
24.2 +++ b/trunk/com/so/news/storage/Purger.java Tue Jan 20 10:21:03 2009 +0100
24.3 @@ -0,0 +1,96 @@
24.4 +/*
24.5 + * StarOffice News Server
24.6 + * see AUTHORS for the list of contributors
24.7 + *
24.8 + * This program is free software: you can redistribute it and/or modify
24.9 + * it under the terms of the GNU General Public License as published by
24.10 + * the Free Software Foundation, either version 3 of the License, or
24.11 + * (at your option) any later version.
24.12 + *
24.13 + * This program is distributed in the hope that it will be useful,
24.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
24.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24.16 + * GNU General Public License for more details.
24.17 + *
24.18 + * You should have received a copy of the GNU General Public License
24.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
24.20 + */
24.21 +
24.22 +package com.so.news.storage;
24.23 +
24.24 +import java.util.Date;
24.25 +
24.26 +import com.so.news.Config;
24.27 +import com.so.news.Debug;
24.28 +
24.29 +/**
24.30 + * The purger is started in configurable intervals to search
24.31 + * for old messages that can be purged.
24.32 + * @author Christian Lins
24.33 + */
24.34 +public class Purger extends Thread
24.35 +{
24.36 + private int interval;
24.37 +
24.38 + public Purger()
24.39 + {
24.40 + setDaemon(true); // Daemons run only along with the main thread
24.41 + setPriority(Thread.MIN_PRIORITY);
24.42 +
24.43 + this.interval = Config.getInstance().get("n3tpd.article.lifetime", 30) * 24 * 60 * 60 * 1000; // Milliseconds
24.44 + if(this.interval < 0)
24.45 + this.interval = Integer.MAX_VALUE;
24.46 + }
24.47 +
24.48 + /**
24.49 + * Runloop of this Purger class.
24.50 + */
24.51 + @Override
24.52 + public void run()
24.53 + {
24.54 + for(;;)
24.55 + {
24.56 + purge();
24.57 +
24.58 + try
24.59 + {
24.60 + sleep(interval);
24.61 + }
24.62 + catch(InterruptedException e)
24.63 + {
24.64 + e.printStackTrace(Debug.getInstance().getStream());
24.65 + }
24.66 + }
24.67 + }
24.68 +
24.69 + /**
24.70 + * Loops through all messages and deletes them if their time
24.71 + * has come.
24.72 + */
24.73 + private void purge()
24.74 + {
24.75 + Debug.getInstance().log("Purging old messages...");
24.76 +
24.77 + try
24.78 + {
24.79 + for(;;)
24.80 + {
24.81 + Article art = null; //Database.getInstance().getOldestArticle();
24.82 + if(art == null) // No articles in the database
24.83 + break;
24.84 +
24.85 + if(art.getDate().getTime() < (new Date().getTime() + this.interval))
24.86 + {
24.87 + Database.getInstance().delete(art);
24.88 + Debug.getInstance().log("Deleted: " + art);
24.89 + }
24.90 + else
24.91 + break;
24.92 + }
24.93 + }
24.94 + catch(Exception ex)
24.95 + {
24.96 + ex.printStackTrace();
24.97 + }
24.98 + }
24.99 +}
25.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
25.2 +++ b/trunk/com/so/news/util/StringTemplate.java Tue Jan 20 10:21:03 2009 +0100
25.3 @@ -0,0 +1,77 @@
25.4 +/*
25.5 + * StarOffice News Server
25.6 + * see AUTHORS for the list of contributors
25.7 + *
25.8 + * This program is free software: you can redistribute it and/or modify
25.9 + * it under the terms of the GNU General Public License as published by
25.10 + * the Free Software Foundation, either version 3 of the License, or
25.11 + * (at your option) any later version.
25.12 + *
25.13 + * This program is distributed in the hope that it will be useful,
25.14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
25.15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25.16 + * GNU General Public License for more details.
25.17 + *
25.18 + * You should have received a copy of the GNU General Public License
25.19 + * along with this program. If not, see <http://www.gnu.org/licenses/>.
25.20 + */
25.21 +
25.22 +package com.so.news.util;
25.23 +
25.24 +import java.util.HashMap;
25.25 +
25.26 +/**
25.27 + * Class that allows simple String template handling.
25.28 + * @author Christian Lins (christian.lins@web.de)
25.29 + */
25.30 +public class StringTemplate
25.31 +{
25.32 + private String str = null;
25.33 + private String templateDelimiter = "%";
25.34 + private HashMap<String, String> templateValues = new HashMap<String, String>();
25.35 +
25.36 + public StringTemplate(String str, String templateDelimiter)
25.37 + {
25.38 + this.str = str;
25.39 + this.templateDelimiter = templateDelimiter;
25.40 + }
25.41 +
25.42 + public StringTemplate(String str)
25.43 + {
25.44 + this(str, "%");
25.45 + }
25.46 +
25.47 + public void set(String template, String value)
25.48 + {
25.49 + this.templateValues.put(template, value);
25.50 + }
25.51 +
25.52 + public void set(String template, long value)
25.53 + {
25.54 + set(template, Long.toString(value));
25.55 + }
25.56 +
25.57 + public void set(String template, double value)
25.58 + {
25.59 + set(template, Double.toString(value));
25.60 + }
25.61 +
25.62 + public void set(String template, Object obj)
25.63 + {
25.64 + set(template, obj.toString());
25.65 + }
25.66 +
25.67 + @Override
25.68 + public String toString()
25.69 + {
25.70 + String ret = new String(str);
25.71 +
25.72 + for(String key : this.templateValues.keySet())
25.73 + {
25.74 + String value = this.templateValues.get(key);
25.75 + ret = ret.replace(templateDelimiter + key, value);
25.76 + }
25.77 +
25.78 + return ret;
25.79 + }
25.80 +}
26.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
26.2 +++ b/trunk/helpers/tbl_mysql6_tmpl.sql Tue Jan 20 10:21:03 2009 +0100
26.3 @@ -0,0 +1,39 @@
26.4 +CREATE DATABASE staroffice_news;
26.5 +
26.6 +CREATE TABLE groups
26.7 +(
26.8 + group_id SERIAL,
26.9 + name VARCHAR(80) NOT NULL,
26.10 + flags INTEGER DEFAULT 0 NOT NULL
26.11 +);
26.12 +
26.13 +CREATE UNIQUE INDEX name_id_index ON groups (name);
26.14 +
26.15 +CREATE TABLE articles
26.16 +(
26.17 + article_id SERIAL,
26.18 + message_id TEXT,
26.19 + header TEXT,
26.20 + body TEXT
26.21 +);
26.22 +
26.23 +CREATE UNIQUE INDEX article_message_index ON articles (message_id(255));
26.24 +
26.25 +CREATE TABLE postings
26.26 +(
26.27 + group_id INTEGER,
26.28 + article_id INTEGER,
26.29 + article_index INTEGER NOT NULL
26.30 +);
26.31 +
26.32 +CREATE UNIQUE INDEX posting_article_index ON postings (article_id);
26.33 +
26.34 +CREATE TABLE subscriptions
26.35 +(
26.36 + group_id INTEGER
26.37 +);
26.38 +
26.39 +CREATE TABLE overview
26.40 +(
26.41 + header TEXT
26.42 +);
27.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
27.2 +++ b/trunk/rfc3977.txt Tue Jan 20 10:21:03 2009 +0100
27.3 @@ -0,0 +1,6998 @@
27.4 +
27.5 +Network Working Group C. Feather
27.6 +Request for Comments: 3977 THUS plc
27.7 +Obsoletes: 977 October 2006
27.8 +Updates: 2980
27.9 +Category: Standards Track
27.10 +
27.11 +
27.12 + Network News Transfer Protocol (NNTP)
27.13 +
27.14 +Status of This Memo
27.15 +
27.16 + This document specifies an Internet standards track protocol for the
27.17 + Internet community, and requests discussion and suggestions for
27.18 + improvements. Please refer to the current edition of the "Internet
27.19 + Official Protocol Standards" (STD 1) for the standardization state
27.20 + and status of this protocol. Distribution of this memo is unlimited.
27.21 +
27.22 +Copyright Notice
27.23 +
27.24 + Copyright (C) The Internet Society (2006).
27.25 +
27.26 +Abstract
27.27 +
27.28 + The Network News Transfer Protocol (NNTP) has been in use in the
27.29 + Internet for a decade, and remains one of the most popular protocols
27.30 + (by volume) in use today. This document is a replacement for
27.31 + RFC 977, and officially updates the protocol specification. It
27.32 + clarifies some vagueness in RFC 977, includes some new base
27.33 + functionality, and provides a specific mechanism to add standardized
27.34 + extensions to NNTP.
27.35 +
27.36 +Table of Contents
27.37 +
27.38 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
27.39 + 1.1. Author's Note . . . . . . . . . . . . . . . . . . . . . . 4
27.40 + 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 5
27.41 + 3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . 6
27.42 + 3.1. Commands and Responses . . . . . . . . . . . . . . . . . 6
27.43 + 3.1.1. Multi-line Data Blocks . . . . . . . . . . . . . . . . 8
27.44 + 3.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 9
27.45 + 3.2.1. Generic Response Codes . . . . . . . . . . . . . . . 10
27.46 + 3.2.1.1. Examples . . . . . . . . . . . . . . . . . . . . 12
27.47 + 3.3. Capabilities and Extensions . . . . . . . . . . . . . . . 14
27.48 + 3.3.1. Capability Descriptions . . . . . . . . . . . . . . . 14
27.49 + 3.3.2. Standard Capabilities . . . . . . . . . . . . . . . . 15
27.50 + 3.3.3. Extensions . . . . . . . . . . . . . . . . . . . . . 16
27.51 + 3.3.4. Initial IANA Register . . . . . . . . . . . . . . . . 18
27.52 + 3.4. Mandatory and Optional Commands . . . . . . . . . . . . . 20
27.53 +
27.54 +
27.55 +
27.56 +Feather Standards Track [Page 1]
27.57 +
27.58 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.59 +
27.60 +
27.61 + 3.4.1. Reading and Transit Servers . . . . . . . . . . . . . 21
27.62 + 3.4.2. Mode Switching . . . . . . . . . . . . . . . . . . . 21
27.63 + 3.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 22
27.64 + 3.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 23
27.65 + 3.6. Articles . . . . . . . . . . . . . . . . . . . . . . . . 24
27.66 + 4. The WILDMAT Format . . . . . . . . . . . . . . . . . . . . . 25
27.67 + 4.1. Wildmat Syntax . . . . . . . . . . . . . . . . . . . . . 26
27.68 + 4.2. Wildmat Semantics . . . . . . . . . . . . . . . . . . . . 26
27.69 + 4.3. Extensions . . . . . . . . . . . . . . . . . . . . . . . 27
27.70 + 4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 27
27.71 + 5. Session Administration Commands . . . . . . . . . . . . . . . 28
27.72 + 5.1. Initial Connection . . . . . . . . . . . . . . . . . . . 28
27.73 + 5.2. CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . 29
27.74 + 5.3. MODE READER . . . . . . . . . . . . . . . . . . . . . . . 32
27.75 + 5.4. QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . 34
27.76 + 6. Article Posting and Retrieval . . . . . . . . . . . . . . . . 35
27.77 + 6.1. Group and Article Selection . . . . . . . . . . . . . . . 36
27.78 + 6.1.1. GROUP . . . . . . . . . . . . . . . . . . . . . . . . 36
27.79 + 6.1.2. LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 39
27.80 + 6.1.3. LAST . . . . . . . . . . . . . . . . . . . . . . . . 42
27.81 + 6.1.4. NEXT . . . . . . . . . . . . . . . . . . . . . . . . 44
27.82 + 6.2. Retrieval of Articles and Article Sections . . . . . . . 45
27.83 + 6.2.1. ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 46
27.84 + 6.2.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 49
27.85 + 6.2.3. BODY . . . . . . . . . . . . . . . . . . . . . . . . 51
27.86 + 6.2.4. STAT . . . . . . . . . . . . . . . . . . . . . . . . 53
27.87 + 6.3. Article Posting . . . . . . . . . . . . . . . . . . . . . 56
27.88 + 6.3.1. POST . . . . . . . . . . . . . . . . . . . . . . . . 56
27.89 + 6.3.2. IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 58
27.90 + 7. Information Commands . . . . . . . . . . . . . . . . . . . . 61
27.91 + 7.1. DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 61
27.92 + 7.2. HELP . . . . . . . . . . . . . . . . . . . . . . . . . . 62
27.93 + 7.3. NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 63
27.94 + 7.4. NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 64
27.95 + 7.5. Time . . . . . . . . . . . . . . . . . . . . . . . . . . 65
27.96 + 7.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 66
27.97 + 7.6. The LIST Commands . . . . . . . . . . . . . . . . . . . . 66
27.98 + 7.6.1. LIST . . . . . . . . . . . . . . . . . . . . . . . . 67
27.99 + 7.6.2. Standard LIST Keywords . . . . . . . . . . . . . . . 69
27.100 + 7.6.3. LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 70
27.101 + 7.6.4. LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 71
27.102 + 7.6.5. LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 72
27.103 + 7.6.6. LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 73
27.104 + 8. Article Field Access Commands . . . . . . . . . . . . . . . . 73
27.105 + 8.1. Article Metadata . . . . . . . . . . . . . . . . . . . . 74
27.106 + 8.1.1. The :bytes Metadata Item . . . . . . . . . . . . . . 74
27.107 + 8.1.2. The :lines Metadata Item . . . . . . . . . . . . . . 75
27.108 + 8.2. Database Consistency . . . . . . . . . . . . . . . . . . 75
27.109 +
27.110 +
27.111 +
27.112 +Feather Standards Track [Page 2]
27.113 +
27.114 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.115 +
27.116 +
27.117 + 8.3. OVER . . . . . . . . . . . . . . . . . . . . . . . . . . 76
27.118 + 8.4. LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 81
27.119 + 8.5. HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
27.120 + 8.6. LIST HEADERS . . . . . . . . . . . . . . . . . . . . . . 87
27.121 + 9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 90
27.122 + 9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 90
27.123 + 9.2. Commands . . . . . . . . . . . . . . . . . . . . . . . . 92
27.124 + 9.3. Command Continuation . . . . . . . . . . . . . . . . . . 93
27.125 + 9.4. Responses . . . . . . . . . . . . . . . . . . . . . . . . 93
27.126 + 9.4.1. Generic Responses . . . . . . . . . . . . . . . . . . 93
27.127 + 9.4.2. Initial Response Line Contents . . . . . . . . . . . 94
27.128 + 9.4.3. Multi-line Response Contents . . . . . . . . . . . . 94
27.129 + 9.5. Capability Lines . . . . . . . . . . . . . . . . . . . . 95
27.130 + 9.6. LIST Variants . . . . . . . . . . . . . . . . . . . . . . 96
27.131 + 9.7. Articles . . . . . . . . . . . . . . . . . . . . . . . . 97
27.132 + 9.8. General Non-terminals . . . . . . . . . . . . . . . . . . 97
27.133 + 9.9. Extensions and Validation . . . . . . . . . . . . . . . . 99
27.134 + 10. Internationalisation Considerations . . . . . . . . . . . . .100
27.135 + 10.1. Introduction and Historical Situation . . . . . . . . . .100
27.136 + 10.2. This Specification . . . . . . . . . . . . . . . . . . .101
27.137 + 10.3. Outstanding Issues . . . . . . . . . . . . . . . . . . .102
27.138 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .103
27.139 + 12. Security Considerations . . . . . . . . . . . . . . . . . . .103
27.140 + 12.1. Personal and Proprietary Information . . . . . . . . . .104
27.141 + 12.2. Abuse of Server Log Information . . . . . . . . . . . . .104
27.142 + 12.3. Weak Authentication and Access Control . . . . . . . . .104
27.143 + 12.4. DNS Spoofing . . . . . . . . . . . . . . . . . . . . . .104
27.144 + 12.5. UTF-8 Issues . . . . . . . . . . . . . . . . . . . . . .105
27.145 + 12.6. Caching of Capability Lists . . . . . . . . . . . . . . .106
27.146 + 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . .107
27.147 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . .110
27.148 + 14.1. Normative References . . . . . . . . . . . . . . . . . .110
27.149 + 14.2. Informative References . . . . . . . . . . . . . . . . .110
27.150 + A. Interaction with Other Specifications . . . . . . . . . . . .112
27.151 + A.1. Header Folding . . . . . . . . . . . . . . . . . . . . .112
27.152 + A.2. Message-IDs . . . . . . . . . . . . . . . . . . . . . . .112
27.153 + A.3. Article Posting . . . . . . . . . . . . . . . . . . . . .114
27.154 + B. Summary of Commands . . . . . . . . . . . . . . . . . . . . .115
27.155 + C. Summary of Response Codes . . . . . . . . . . . . . . . . . .117
27.156 + D. Changes from RFC 977 . . . . . . . . . . . . . . . . . . . .121
27.157 +
27.158 +1. Introduction
27.159 +
27.160 + This document specifies the Network News Transfer Protocol (NNTP),
27.161 + which is used for the distribution, inquiry, retrieval, and posting
27.162 + of Netnews articles using a reliable stream-based mechanism. For
27.163 + news-reading clients, NNTP enables retrieval of news articles that
27.164 +
27.165 +
27.166 +
27.167 +
27.168 +Feather Standards Track [Page 3]
27.169 +
27.170 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.171 +
27.172 +
27.173 + are stored in a central database, giving subscribers the ability to
27.174 + select only those articles they wish to read.
27.175 +
27.176 + The Netnews model provides for indexing, cross-referencing, and
27.177 + expiration of aged messages. NNTP is designed for efficient
27.178 + transmission of Netnews articles over a reliable full duplex
27.179 + communication channel.
27.180 +
27.181 + Although the protocol specification in this document is largely
27.182 + compatible with the version specified in RFC 977 [RFC977], a number
27.183 + of changes are summarised in Appendix D. In particular:
27.184 +
27.185 + o the default character set is changed from US-ASCII [ANSI1986] to
27.186 + UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8);
27.187 +
27.188 + o a number of commands that were optional in RFC 977 or that have
27.189 + been taken from RFC 2980 [RFC2980] are now mandatory; and
27.190 +
27.191 + o a CAPABILITIES command has been added to allow clients to
27.192 + determine what functionality is available from a server.
27.193 +
27.194 + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
27.195 + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
27.196 + document are to be interpreted as described in RFC 2119 [RFC2119].
27.197 +
27.198 + An implementation is not compliant if it fails to satisfy one or more
27.199 + of the MUST requirements for this protocol. An implementation that
27.200 + satisfies all the MUST and all the SHOULD requirements for its
27.201 + protocols is said to be "unconditionally compliant"; one that
27.202 + satisfies all the MUST requirements but not all the SHOULD
27.203 + requirements for NNTP is said to be "conditionally compliant".
27.204 +
27.205 + For the remainder of this document, the terms "client" and "client
27.206 + host" refer to a host making use of the NNTP service, while the terms
27.207 + "server" and "server host" refer to a host that offers the NNTP
27.208 + service.
27.209 +
27.210 +1.1. Author's Note
27.211 +
27.212 + This document is written in XML using an NNTP-specific DTD. Custom
27.213 + software is used to convert this to RFC 2629 [RFC2629] format, and
27.214 + then the public "xml2rfc" package to further reduce this to text,
27.215 + nroff source, and HTML.
27.216 +
27.217 + No perl was used in producing this document.
27.218 +
27.219 +
27.220 +
27.221 +
27.222 +
27.223 +
27.224 +Feather Standards Track [Page 4]
27.225 +
27.226 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.227 +
27.228 +
27.229 +2. Notation
27.230 +
27.231 + The following notational conventions are used in this document.
27.232 +
27.233 + UPPERCASE indicates literal text to be included in the
27.234 + command.
27.235 +
27.236 + lowercase indicates a token described elsewhere.
27.237 +
27.238 + [brackets] indicate that the enclosed material is optional.
27.239 +
27.240 + elliptical indicates that the argument may be repeated any
27.241 + ... marks number of times (it must occur at least once).
27.242 +
27.243 + vertical|bar indicates a choice of two mutually exclusive
27.244 + arguments (exactly one must be provided).
27.245 +
27.246 + The name "message-id" for a command or response argument indicates
27.247 + that it is the message-id of an article as described in Section 3.6,
27.248 + including the angle brackets.
27.249 +
27.250 + The name "wildmat" for an argument indicates that it is a wildmat as
27.251 + defined in Section 4. If the argument does not meet the requirements
27.252 + of that section (for example, if it does not fit the grammar of
27.253 + Section 4.1), the NNTP server MAY place some interpretation on it
27.254 + (not specified by this document) or otherwise MUST treat it as a
27.255 + syntax error.
27.256 +
27.257 + Responses for each command will be described in tables listing the
27.258 + required format of a response followed by the meaning that should be
27.259 + ascribed to that response.
27.260 +
27.261 + The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets
27.262 + %x00, %x09, %x0A, %x0D, and %x20, respectively (that is, the octets
27.263 + with those codes in US-ASCII [ANSI1986] and thus in UTF-8 [RFC3629]).
27.264 + The term "CRLF" or "CRLF pair" means the sequence CR immediately
27.265 + followed by LF (that is, %x0D.0A). A "printable US-ASCII character"
27.266 + is an octet in the range %x21-7E. Quoted characters refer to the
27.267 + octets with those codes in US-ASCII (so "." and "<" refer to %x2E and
27.268 + %x3C) and will always be printable US-ASCII characters; similarly,
27.269 + "digit" refers to the octets %x30-39.
27.270 +
27.271 + A "keyword" MUST consist only of US-ASCII letters, digits, and the
27.272 + characters dot (".") and dash ("-") and MUST begin with a letter.
27.273 + Keywords MUST be at least three characters in length.
27.274 +
27.275 +
27.276 +
27.277 +
27.278 +
27.279 +
27.280 +Feather Standards Track [Page 5]
27.281 +
27.282 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.283 +
27.284 +
27.285 + Examples in this document are not normative but serve to illustrate
27.286 + usages, arguments, and responses. In the examples, a "[C]" will be
27.287 + used to represent the client host and an "[S]" will be used to
27.288 + represent the server host. Most of the examples do not rely on a
27.289 + particular server state. In some cases, however, they do assume that
27.290 + the currently selected newsgroup (see the GROUP command,
27.291 + Section 6.1.1) is invalid; when so, this is indicated at the start of
27.292 + the example. Examples may use commands or other keywords not defined
27.293 + in this specification (such as an XENCRYPT command). These will be
27.294 + used to illustrate some point and do not imply that any such command
27.295 + is defined elsewhere or needs to exist in any particular
27.296 + implementation.
27.297 +
27.298 + Terms that might be read as specifying details of a client or server
27.299 + implementation, such as "database", are used simply to ease
27.300 + description. Provided that implementations conform to the protocol
27.301 + and format specifications in this document, no specific technique is
27.302 + mandated.
27.303 +
27.304 +3. Basic Concepts
27.305 +
27.306 +3.1. Commands and Responses
27.307 +
27.308 + NNTP operates over any reliable bi-directional 8-bit-wide data stream
27.309 + channel. When the connection is established, the NNTP server host
27.310 + MUST send a greeting. The client host and server host then exchange
27.311 + commands and responses (respectively) until the connection is closed
27.312 + or aborted. If the connection used is TCP, then the server host
27.313 + starts the NNTP service by listening on a TCP port. When a client
27.314 + host wishes to make use of the service, it MUST establish a TCP
27.315 + connection with the server host by connecting to that host on the
27.316 + same port on which the server is listening.
27.317 +
27.318 + The character set for all NNTP commands is UTF-8 [RFC3629]. Commands
27.319 + in NNTP MUST consist of a keyword, which MAY be followed by one or
27.320 + more arguments. A CRLF pair MUST terminate all commands. Multiple
27.321 + commands MUST NOT be on the same line. Unless otherwise noted
27.322 + elsewhere in this document, arguments SHOULD consist of printable US-
27.323 + ASCII characters. Keywords and arguments MUST each be separated by
27.324 + one or more space or TAB characters. Command lines MUST NOT exceed
27.325 + 512 octets, which includes the terminating CRLF pair. The arguments
27.326 + MUST NOT exceed 497 octets. A server MAY relax these limits for
27.327 + commands defined in an extension.
27.328 +
27.329 + Where this specification permits UTF-8 characters outside the range
27.330 + of U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark
27.331 + (U+FEFF, encoding %xEF.BB.BF) and MUST use the Word Joiner (U+2060,
27.332 + encoding %xE2.91.A0) for the meaning Zero Width No-Break Space in
27.333 +
27.334 +
27.335 +
27.336 +Feather Standards Track [Page 6]
27.337 +
27.338 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.339 +
27.340 +
27.341 + command lines and the initial lines of responses. Implementations
27.342 + SHOULD apply these same principles throughout.
27.343 +
27.344 + The term "character" means a single Unicode code point.
27.345 + Implementations are not required to carry out Unicode normalisation.
27.346 + Thus, U+0084 (A-dieresis) is one character, while U+0041 U+0308 (A
27.347 + composed with dieresis) is two; the two need not be treated as
27.348 + equivalent.
27.349 +
27.350 + Commands may have variants; if so, they use a second keyword
27.351 + immediately after the first to indicate which variant is required.
27.352 + The only such commands in this specification are LIST and MODE. Note
27.353 + that such variants are sometimes referred to as if they were commands
27.354 + in their own right: "the LIST ACTIVE" command should be read as
27.355 + shorthand for "the ACTIVE variant of the LIST command".
27.356 +
27.357 + Keywords are case insensitive; the case of keywords for commands MUST
27.358 + be ignored by the server. Command and response arguments are case or
27.359 + language specific only when stated, either in this document or in
27.360 + other relevant specifications.
27.361 +
27.362 + In some cases, a command involves more data than just a single line.
27.363 + The further data may be sent either immediately after the command
27.364 + line (there are no instances of this in this specification, but there
27.365 + are in extensions such as [NNTP-STREAM]) or following a request from
27.366 + the server (indicated by a 3xx response).
27.367 +
27.368 + Each response MUST start with a three-digit response code that is
27.369 + sufficient to distinguish all responses. Certain valid responses are
27.370 + defined to be multi-line; for all others, the response is contained
27.371 + in a single line. The initial line of the response MUST NOT exceed
27.372 + 512 octets, which includes the response code and the terminating CRLF
27.373 + pair; an extension MAY specify a greater maximum for commands that it
27.374 + defines, but not for any other command. Single-line responses
27.375 + consist of an initial line only. Multi-line responses consist of an
27.376 + initial line followed by a multi-line data block.
27.377 +
27.378 + An NNTP server MAY have an inactivity autologout timer. Such a timer
27.379 + SHOULD be of at least three minutes' duration, with the exception
27.380 + that there MAY be a shorter limit on how long the server is willing
27.381 + to wait for the first command from the client. The receipt of any
27.382 + command from the client during the timer interval SHOULD suffice to
27.383 + reset the autologout timer. Similarly, the receipt of any
27.384 + significant amount of data from a client that is sending a multi-line
27.385 + data block (such as during a POST or IHAVE command) SHOULD suffice to
27.386 + reset the autologout timer. When the timer expires, the server
27.387 + SHOULD close the connection without sending any response to the
27.388 + client.
27.389 +
27.390 +
27.391 +
27.392 +Feather Standards Track [Page 7]
27.393 +
27.394 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.395 +
27.396 +
27.397 +3.1.1. Multi-line Data Blocks
27.398 +
27.399 + A multi-line data block is used in certain commands and responses.
27.400 + It MUST adhere to the following rules:
27.401 +
27.402 + 1. The block consists of a sequence of zero or more "lines", each
27.403 + being a stream of octets ending with a CRLF pair. Apart from
27.404 + those line endings, the stream MUST NOT include the octets NUL,
27.405 + LF, or CR.
27.406 +
27.407 + 2. In a multi-line response, the block immediately follows the CRLF
27.408 + at the end of the initial line of the response. When used in any
27.409 + other context, the specific command will define when the block is
27.410 + sent.
27.411 +
27.412 + 3. If any line of the data block begins with the "termination octet"
27.413 + ("." or %x2E), that line MUST be "dot-stuffed" by prepending an
27.414 + additional termination octet to that line of the block.
27.415 +
27.416 + 4. The lines of the block MUST be followed by a terminating line
27.417 + consisting of a single termination octet followed by a CRLF pair
27.418 + in the normal way. Thus, unless it is empty, a multi-line block
27.419 + is always terminated with the five octets CRLF "." CRLF
27.420 + (%x0D.0A.2E.0D.0A).
27.421 +
27.422 + 5. When a multi-line block is interpreted, the "dot-stuffing" MUST
27.423 + be undone; i.e., the recipient MUST ensure that, in any line
27.424 + beginning with the termination octet followed by octets other
27.425 + than a CRLF pair, that initial termination octet is disregarded.
27.426 +
27.427 + 6. Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT
27.428 + be considered part of the multi-line block; i.e., the recipient
27.429 + MUST ensure that any line beginning with the termination octet
27.430 + followed immediately by a CRLF pair is disregarded. (The first
27.431 + CRLF pair of the terminating CRLF "." CRLF of a non-empty block
27.432 + is, of course, part of the last line of the block.)
27.433 +
27.434 + Note that texts using an encoding (such as UTF-16 or UTF-32) that may
27.435 + contain the octets NUL, LF, or CR other than a CRLF pair cannot be
27.436 + reliably conveyed in the above format (that is, they violate the MUST
27.437 + requirement above). However, except when stated otherwise, this
27.438 + specification does not require the content to be UTF-8, and therefore
27.439 + (subject to that same requirement) it MAY include octets above and
27.440 + below 128 mixed arbitrarily.
27.441 +
27.442 + This document does not place any limit on the length of a line in a
27.443 + multi-line block. However, the standards that define the format of
27.444 + articles may do so.
27.445 +
27.446 +
27.447 +
27.448 +Feather Standards Track [Page 8]
27.449 +
27.450 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.451 +
27.452 +
27.453 +3.2. Response Codes
27.454 +
27.455 + Each response MUST begin with a three-digit status indicator. These
27.456 + are status reports from the server and indicate the response to the
27.457 + last command received from the client.
27.458 +
27.459 + The first digit of the response broadly indicates the success,
27.460 + failure, or progress of the previous command:
27.461 +
27.462 + 1xx - Informative message
27.463 + 2xx - Command completed OK
27.464 + 3xx - Command OK so far; send the rest of it
27.465 + 4xx - Command was syntactically correct but failed for some reason
27.466 + 5xx - Command unknown, unsupported, unavailable, or syntax error
27.467 +
27.468 + The next digit in the code indicates the function response category:
27.469 +
27.470 + x0x - Connection, setup, and miscellaneous messages
27.471 + x1x - Newsgroup selection
27.472 + x2x - Article selection
27.473 + x3x - Distribution functions
27.474 + x4x - Posting
27.475 + x8x - Reserved for authentication and privacy extensions
27.476 + x9x - Reserved for private use (non-standard extensions)
27.477 +
27.478 + Certain responses contain arguments such as numbers and names in
27.479 + addition to the status indicator. In those cases, to simplify
27.480 + interpretation by the client, the number and type of such arguments
27.481 + is fixed for each response code, as is whether the code is
27.482 + single-line or multi-line. Any extension MUST follow this principle
27.483 + as well. Note that, for historical reasons, the 211 response code is
27.484 + an exception to this in that the response may be single-line or
27.485 + multi-line depending on the command (GROUP or LISTGROUP) that
27.486 + generated it. In all other cases, the client MUST only use the
27.487 + status indicator itself to determine the nature of the response. The
27.488 + exact response codes that can be returned by any given command are
27.489 + detailed in the description of that command.
27.490 +
27.491 + Arguments MUST be separated from the numeric status indicator and
27.492 + from each other by a single space. All numeric arguments MUST be in
27.493 + base 10 (decimal) format and MAY have leading zeros. String
27.494 + arguments MUST contain at least one character and MUST NOT contain
27.495 + TAB, LF, CR, or space. The server MAY add any text after the
27.496 + response code or last argument, as appropriate, and the client MUST
27.497 + NOT make decisions based on this text. Such text MUST be separated
27.498 + from the numeric status indicator or the last argument by at least
27.499 + one space.
27.500 +
27.501 +
27.502 +
27.503 +
27.504 +Feather Standards Track [Page 9]
27.505 +
27.506 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.507 +
27.508 +
27.509 + The server MUST respond to any command with the appropriate generic
27.510 + response (given in Section 3.2.1) if it represents the situation.
27.511 + Otherwise, each recognized command MUST return one of the response
27.512 + codes specifically listed in its description or in an extension. A
27.513 + server MAY provide extensions to this specification, including new
27.514 + commands, new variants or features of existing commands, and other
27.515 + ways of changing the internal state of the server. However, the
27.516 + server MUST NOT produce any other responses to a client that does not
27.517 + invoke any of the additional features. (Therefore, a client that
27.518 + restricts itself to this specification will only receive the
27.519 + responses that are listed.)
27.520 +
27.521 + If a client receives an unexpected response, it SHOULD use the first
27.522 + digit of the response to determine the result. For example, an
27.523 + unexpected 2xx should be taken as success, and an unexpected 4xx or
27.524 + 5xx as failure.
27.525 +
27.526 + Response codes not specified in this document MAY be used for any
27.527 + installation-specific additional commands also not specified. These
27.528 + SHOULD be chosen to fit the pattern of x9x specified above.
27.529 +
27.530 + Neither this document nor any registered extension (see
27.531 + Section 3.3.3) will specify any response codes of the x9x pattern.
27.532 + (Implementers of extensions are accordingly cautioned not to use such
27.533 + responses for extensions that may subsequently be submitted for
27.534 + registration.)
27.535 +
27.536 +3.2.1. Generic Response Codes
27.537 +
27.538 + The server MUST respond to any command with the appropriate one of
27.539 + the following generic responses if it represents the situation.
27.540 +
27.541 + If the command is not recognized, or if it is an optional command
27.542 + that is not implemented by the server, the response code 500 MUST be
27.543 + returned.
27.544 +
27.545 + If there is a syntax error in the arguments of a recognized command,
27.546 + including the case where more arguments are provided than the command
27.547 + specifies or the command line is longer than the server accepts, the
27.548 + response code 501 MUST be returned. The line MUST NOT be truncated
27.549 + or split and then interpreted. Note that where a command has
27.550 + variants depending on a second keyword (e.g., LIST ACTIVE and LIST
27.551 + NEWSGROUPS), 501 MUST be used when the base command is implemented
27.552 + but the requested variant is not, and 500 MUST be used only when the
27.553 + base command itself is not implemented.
27.554 +
27.555 + If an argument is required to be a base64-encoded string [RFC4648]
27.556 + (there are no such arguments in this specification, but there may be
27.557 +
27.558 +
27.559 +
27.560 +Feather Standards Track [Page 10]
27.561 +
27.562 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.563 +
27.564 +
27.565 + in extensions) and is not validly encoded, the response code 504 MUST
27.566 + be returned.
27.567 +
27.568 + If the server experiences an internal fault or problem that means it
27.569 + is unable to carry out the command (for example, a necessary file is
27.570 + missing or a necessary service could not be contacted), the response
27.571 + code 403 MUST be returned. If the server recognizes the command but
27.572 + does not provide an optional feature (for example, because it does
27.573 + not store the required information), or if it only handles a subset
27.574 + of legitimate cases (see the HDR command, Section 8.5, for an
27.575 + example), the response code 503 MUST be returned.
27.576 +
27.577 + If the client is not authorized to use the specified facility when
27.578 + the server is in its current state, then the appropriate one of the
27.579 + following response codes MUST be used.
27.580 +
27.581 + 502: It is necessary to terminate the connection and to start a new
27.582 + one with the appropriate authority before the command can be used.
27.583 + Historically, some mode-switching servers (see Section 3.4.1) used
27.584 + this response to indicate that this command will become available
27.585 + after the MODE READER command (Section 5.3) is used, but this
27.586 + usage does not conform to this specification and MUST NOT be used.
27.587 + Note that the server MUST NOT close the connection immediately
27.588 + after a 502 response except at the initial connection
27.589 + (Section 5.1) and with the MODE READER command.
27.590 +
27.591 + 480: The client must authenticate itself to the server (that is, it
27.592 + must provide information as to the identity of the client) before
27.593 + the facility can be used on this connection. This will involve
27.594 + the use of an authentication extension such as [NNTP-AUTH].
27.595 +
27.596 + 483: The client must negotiate appropriate privacy protection on the
27.597 + connection. This will involve the use of a privacy extension such
27.598 + as [NNTP-TLS].
27.599 +
27.600 + 401: The client must change the state of the connection in some other
27.601 + manner. The first argument of the response MUST be the capability
27.602 + label (see Section 5.2) of the facility that provides the
27.603 + necessary mechanism (usually an extension, which may be a private
27.604 + extension). The server MUST NOT use this response code except as
27.605 + specified by the definition of the capability in question.
27.606 +
27.607 + If the server has to terminate the connection for some reason, it
27.608 + MUST give a 400 response code to the next command and then
27.609 + immediately close the connection. Following a 400 response, clients
27.610 + SHOULD NOT simply reconnect immediately and retry the same actions.
27.611 + Rather, a client SHOULD either use an exponentially increasing delay
27.612 + between retries (e.g., double the waiting time after each 400
27.613 +
27.614 +
27.615 +
27.616 +Feather Standards Track [Page 11]
27.617 +
27.618 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.619 +
27.620 +
27.621 + response) or present any associated text to the user for them to
27.622 + decide whether and when to retry.
27.623 +
27.624 + The client MUST be prepared to receive any of these responses for any
27.625 + command (except, of course, that the server MUST NOT generate a 500
27.626 + response code for mandatory commands).
27.627 +
27.628 +3.2.1.1. Examples
27.629 +
27.630 + Example of an unknown command:
27.631 +
27.632 + [C] MAIL
27.633 + [S] 500 Unknown command
27.634 +
27.635 + Example of an unsupported command:
27.636 +
27.637 + [C] CAPABILITIES
27.638 + [S] 101 Capability list:
27.639 + [S] VERSION 2
27.640 + [S] READER
27.641 + [S] NEWNEWS
27.642 + [S] LIST ACTIVE NEWSGROUPS
27.643 + [S] .
27.644 + [C] OVER
27.645 + [S] 500 Unknown command
27.646 +
27.647 + Example of an unsupported variant:
27.648 +
27.649 + [C] MODE POSTER
27.650 + [S] 501 Unknown MODE option
27.651 +
27.652 + Example of a syntax error:
27.653 +
27.654 + [C] ARTICLE a.message.id@no.angle.brackets
27.655 + [S] 501 Syntax error
27.656 +
27.657 + Example of an overlong command line:
27.658 +
27.659 + [C] HEAD 53 54 55
27.660 + [S] 501 Too many arguments
27.661 +
27.662 + Example of a bad wildmat:
27.663 +
27.664 + [C] LIST ACTIVE u[ks].*
27.665 + [S] 501 Syntax error
27.666 +
27.667 +
27.668 +
27.669 +
27.670 +
27.671 +
27.672 +Feather Standards Track [Page 12]
27.673 +
27.674 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.675 +
27.676 +
27.677 + Example of a base64-encoding error (the second argument is meant to
27.678 + be base64 encoded):
27.679 +
27.680 + [C] XENCRYPT RSA abcd=efg
27.681 + [S] 504 Base64 encoding error
27.682 +
27.683 + Example of an attempt to access a facility not available to this
27.684 + connection:
27.685 +
27.686 + [C] MODE READER
27.687 + [S] 200 Reader mode, posting permitted
27.688 + [C] IHAVE <i.am.an.article.you.will.want@example.com>
27.689 + [S] 500 Permission denied
27.690 +
27.691 + Example of an attempt to access a facility requiring authentication:
27.692 +
27.693 + [C] GROUP secret.group
27.694 + [S] 480 Permission denied
27.695 +
27.696 + Example of a successful attempt following such authentication:
27.697 +
27.698 + [C] XSECRET fred flintstone
27.699 + [S] 290 Password for fred accepted
27.700 + [C] GROUP secret.group
27.701 + [S] 211 5 1 20 secret.group selected
27.702 +
27.703 + Example of an attempt to access a facility requiring privacy:
27.704 +
27.705 + [C] GROUP secret.group
27.706 + [S] 483 Secure connection required
27.707 + [C] XENCRYPT
27.708 + [Client and server negotiate encryption on the link]
27.709 + [S] 283 Encrypted link established
27.710 + [C] GROUP secret.group
27.711 + [S] 211 5 1 20 secret.group selected
27.712 +
27.713 + Example of a need to change mode before a facility is used:
27.714 +
27.715 + [C] GROUP binary.group
27.716 + [S] 401 XHOST Not on this virtual host
27.717 + [C] XHOST binary.news.example.org
27.718 + [S] 290 binary.news.example.org virtual host selected
27.719 + [C] GROUP binary.group
27.720 + [S] 211 5 1 77 binary.group selected
27.721 +
27.722 +
27.723 +
27.724 +
27.725 +
27.726 +
27.727 +
27.728 +Feather Standards Track [Page 13]
27.729 +
27.730 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.731 +
27.732 +
27.733 + Example of a temporary failure:
27.734 +
27.735 + [C] GROUP archive.local
27.736 + [S] 403 Archive server temporarily offline
27.737 +
27.738 + Example of the server needing to close down immediately:
27.739 +
27.740 + [C] ARTICLE 123
27.741 + [S] 400 Power supply failed, running on UPS
27.742 + [Server closes connection.]
27.743 +
27.744 +3.3. Capabilities and Extensions
27.745 +
27.746 + Not all NNTP servers provide exactly the same facilities, both
27.747 + because this specification allows variation and because servers may
27.748 + provide extensions. A set of facilities that are related are called
27.749 + a "capability". This specification provides a way to determine what
27.750 + capabilities are available, includes a list of standard capabilities,
27.751 + and includes a mechanism (the extension mechanism) for defining new
27.752 + capabilities.
27.753 +
27.754 +3.3.1. Capability Descriptions
27.755 +
27.756 + A client can determine the available capabilities of the server by
27.757 + using the CAPABILITIES command (Section 5.2). This returns a
27.758 + capability list, which is a list of capability lines. Each line
27.759 + describes one available capability.
27.760 +
27.761 + Each capability line consists of one or more tokens, which MUST be
27.762 + separated by one or more space or TAB characters. A token is a
27.763 + string of 1 or more printable UTF-8 characters (that is, either
27.764 + printable US-ASCII characters or any UTF-8 sequence outside the US-
27.765 + ASCII range, but not space or TAB). Unless stated otherwise, tokens
27.766 + are case insensitive. Each capability line consists of the
27.767 + following:
27.768 +
27.769 + o The capability label, which is a keyword indicating the
27.770 + capability. A capability label may be defined by this
27.771 + specification or a successor, or by an extension.
27.772 +
27.773 + o The label is then followed by zero or more tokens, which are
27.774 + arguments of the capability. The form and meaning of these tokens
27.775 + is specific to each capability.
27.776 +
27.777 + The server MUST ensure that the capability list accurately reflects
27.778 + the capabilities (including extensions) currently available. If a
27.779 + capability is only available with the server in a certain state (for
27.780 + example, only after authentication), the list MUST only include the
27.781 +
27.782 +
27.783 +
27.784 +Feather Standards Track [Page 14]
27.785 +
27.786 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.787 +
27.788 +
27.789 + capability label when the server is in that state. Similarly, if
27.790 + only some of the commands in an extension will be available, or if
27.791 + the behaviour of the extension will change in some other manner,
27.792 + according to the state of the server, this MUST be indicated by
27.793 + different arguments in the capability line.
27.794 +
27.795 + Note that a capability line can only begin with a letter. Lines
27.796 + beginning with other characters are reserved for future versions of
27.797 + this specification. In order to interoperate with such versions,
27.798 + clients MUST be prepared to receive lines beginning with other
27.799 + characters and MUST ignore any they do not understand.
27.800 +
27.801 +3.3.2. Standard Capabilities
27.802 +
27.803 + The following capabilities are defined by this specification.
27.804 +
27.805 + VERSION
27.806 + This capability MUST be advertised by all servers and MUST be the
27.807 + first capability in the capability list; it indicates the
27.808 + version(s) of NNTP that the server supports. There must be at
27.809 + least one argument; each argument is a decimal number and MUST NOT
27.810 + have a leading zero. Version numbers are assigned only in RFCs
27.811 + that update or replace this specification; servers MUST NOT create
27.812 + their own version numbers.
27.813 +
27.814 + The version number of this specification is 2.
27.815 +
27.816 + READER
27.817 + This capability indicates that the server implements the various
27.818 + commands useful for reading clients.
27.819 +
27.820 + IHAVE
27.821 + This capability indicates that the server implements the IHAVE
27.822 + command.
27.823 +
27.824 + POST
27.825 + This capability indicates that the server implements the POST
27.826 + command.
27.827 +
27.828 + NEWNEWS
27.829 + This capability indicates that the server implements the NEWNEWS
27.830 + command.
27.831 +
27.832 + HDR
27.833 + This capability indicates that the server implements the header
27.834 + access commands (HDR and LIST HEADERS).
27.835 +
27.836 +
27.837 +
27.838 +
27.839 +
27.840 +Feather Standards Track [Page 15]
27.841 +
27.842 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.843 +
27.844 +
27.845 + OVER
27.846 + This capability indicates that the server implements the overview
27.847 + access commands (OVER and LIST OVERVIEW.FMT). If and only if the
27.848 + server supports the message-id form of the OVER command, there
27.849 + must be a single argument MSGID.
27.850 +
27.851 + LIST
27.852 + This capability indicates that the server implements at least one
27.853 + variant of the LIST command. There MUST be one argument for each
27.854 + variant of the LIST command supported by the server, giving the
27.855 + keyword for that variant.
27.856 +
27.857 + IMPLEMENTATION
27.858 + This capability MAY be provided by a server. If so, the arguments
27.859 + SHOULD be used to provide information such as the server software
27.860 + name and version number. The client MUST NOT use this line to
27.861 + determine capabilities of the server. (While servers often
27.862 + provide this information in the initial greeting, clients need to
27.863 + guess whether this is the case; this capability makes it clear
27.864 + what the information is.)
27.865 +
27.866 + MODE-READER
27.867 + This capability indicates that the server is mode-switching
27.868 + (Section 3.4.2) and that the MODE READER command needs to be used
27.869 + to enable the READER capability.
27.870 +
27.871 +3.3.3. Extensions
27.872 +
27.873 + Although NNTP is widely and robustly deployed, some parts of the
27.874 + Internet community might wish to extend the NNTP service. It must be
27.875 + emphasized that any extension to NNTP should not be considered
27.876 + lightly. NNTP's strength comes primarily from its simplicity.
27.877 + Experience with many protocols has shown that:
27.878 +
27.879 + Protocols with few options tend towards ubiquity, whilst protocols
27.880 + with many options tend towards obscurity.
27.881 +
27.882 + This means that each and every extension, regardless of its benefits,
27.883 + must be carefully scrutinized with respect to its implementation,
27.884 + deployment, and interoperability costs. In many cases, the cost of
27.885 + extending the NNTP service will likely outweigh the benefit.
27.886 +
27.887 + An extension is a package of associated facilities, often but not
27.888 + always including one or more new commands. Each extension MUST
27.889 + define at least one new capability label (this will often, but need
27.890 + not, be the name of one of these new commands). While any additional
27.891 + capability information can normally be specified using arguments to
27.892 +
27.893 +
27.894 +
27.895 +
27.896 +Feather Standards Track [Page 16]
27.897 +
27.898 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.899 +
27.900 +
27.901 + that label, an extension MAY define more than one capability label.
27.902 + However, this SHOULD be limited to exceptional circumstances.
27.903 +
27.904 + An extension is either a private extension, or its capabilities are
27.905 + included in the IANA registry of capabilities (see Section 3.3.4) and
27.906 + it is defined in an RFC (in which case it is a "registered
27.907 + extension"). Such RFCs either must be on the standards track or must
27.908 + define an IESG-approved experimental protocol.
27.909 +
27.910 + The definition of an extension must include the following:
27.911 +
27.912 + o a descriptive name for the extension.
27.913 +
27.914 + o the capability label or labels defined by the extension (the
27.915 + capability label of a registered extension MUST NOT begin with
27.916 + "X").
27.917 +
27.918 + o The syntax, values, and meanings of any arguments for each
27.919 + capability label defined by the extension.
27.920 +
27.921 + o Any new NNTP commands associated with the extension (the names of
27.922 + commands associated with registered extensions MUST NOT begin with
27.923 + "X").
27.924 +
27.925 + o The syntax and possible values of arguments associated with the
27.926 + new NNTP commands.
27.927 +
27.928 + o The response codes and possible values of arguments for the
27.929 + responses of the new NNTP commands.
27.930 +
27.931 + o Any new arguments the extension associates with any other
27.932 + pre-existing NNTP commands.
27.933 +
27.934 + o Any increase in the maximum length of commands and initial
27.935 + response lines over the value specified in this document.
27.936 +
27.937 + o A specific statement about the effect on pipelining that this
27.938 + extension may have (if any).
27.939 +
27.940 + o A specific statement about the circumstances when use of this
27.941 + extension can alter the contents of the capabilities list (other
27.942 + than the new capability labels it defines).
27.943 +
27.944 + o A specific statement about the circumstances under which the
27.945 + extension can cause any pre-existing command to produce a 401,
27.946 + 480, or 483 response.
27.947 +
27.948 +
27.949 +
27.950 +
27.951 +
27.952 +Feather Standards Track [Page 17]
27.953 +
27.954 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.955 +
27.956 +
27.957 + o A description of how the use of MODE READER on a mode-switching
27.958 + server interacts with the extension.
27.959 +
27.960 + o A description of how support for the extension affects the
27.961 + behaviour of a server and NNTP client in any other manner not
27.962 + outlined above.
27.963 +
27.964 + o Formal syntax as described in Section 9.9.
27.965 +
27.966 + A private extension MAY or MAY NOT be included in the capabilities
27.967 + list. If it is, the capability label MUST begin with "X". A server
27.968 + MAY provide additional keywords (for new commands and also for new
27.969 + variants of existing commands) as part of a private extension. To
27.970 + avoid the risk of a clash with a future registered extension, these
27.971 + keywords SHOULD begin with "X".
27.972 +
27.973 + If the server advertises a capability defined by a registered
27.974 + extension, it MUST implement the extension so as to fully conform
27.975 + with the specification (for example, it MUST implement all the
27.976 + commands that the extension describes as mandatory). If it does not
27.977 + implement the extension as specified, it MUST NOT list the extension
27.978 + in the capabilities list under its registered name. In that case, it
27.979 + MAY, but SHOULD NOT, provide a private extension (not listed, or
27.980 + listed with a different name) that implements part of the extension
27.981 + or implements the commands of the extension with a different meaning.
27.982 +
27.983 + A server MUST NOT send different response codes to basic NNTP
27.984 + commands documented here or to commands documented in registered
27.985 + extensions in response to the availability or use of a private
27.986 + extension.
27.987 +
27.988 +3.3.4. Initial IANA Register
27.989 +
27.990 + IANA will maintain a registry of NNTP capability labels. All
27.991 + capability labels in the registry MUST be keywords and MUST NOT begin
27.992 + with X.
27.993 +
27.994 +
27.995 +
27.996 +
27.997 +
27.998 +
27.999 +
27.1000 +
27.1001 +
27.1002 +
27.1003 +
27.1004 +
27.1005 +
27.1006 +
27.1007 +
27.1008 +Feather Standards Track [Page 18]
27.1009 +
27.1010 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1011 +
27.1012 +
27.1013 + The initial content of the registry consists of these entries:
27.1014 +
27.1015 + +-------------------+--------------------------+--------------------+
27.1016 + | Label | Meaning | Definition |
27.1017 + +-------------------+--------------------------+--------------------+
27.1018 + | AUTHINFO | Authentication | [NNTP-AUTH] |
27.1019 + | | | |
27.1020 + | HDR | Batched header retrieval | Section 3.3.2, |
27.1021 + | | | Section 8.5, and |
27.1022 + | | | Section 8.6 |
27.1023 + | | | |
27.1024 + | IHAVE | IHAVE command available | Section 3.3.2 and |
27.1025 + | | | Section 6.3.2 |
27.1026 + | | | |
27.1027 + | IMPLEMENTATION | Server | Section 3.3.2 |
27.1028 + | | implementation-specific | |
27.1029 + | | information | |
27.1030 + | | | |
27.1031 + | LIST | LIST command variants | Section 3.3.2 and |
27.1032 + | | | Section 7.6.1 |
27.1033 + | | | |
27.1034 + | MODE-READER | Mode-switching server | Section 3.4.2 |
27.1035 + | | and MODE READER command | |
27.1036 + | | available | |
27.1037 + | | | |
27.1038 + | NEWNEWS | NEWNEWS command | Section 3.3.2 and |
27.1039 + | | available | Section 7.4 |
27.1040 + | | | |
27.1041 + | OVER | Overview support | Section 3.3.2, |
27.1042 + | | | Section 8.3, and |
27.1043 + | | | Section 8.4 |
27.1044 + | | | |
27.1045 + | POST | POST command available | Section 3.3.2 and |
27.1046 + | | | Section 6.3.1 |
27.1047 + | | | |
27.1048 + | READER | Reader commands | Section 3.3.2 |
27.1049 + | | available | |
27.1050 + | | | |
27.1051 + | SASL | Supported SASL | [NNTP-AUTH] |
27.1052 + | | mechanisms | |
27.1053 + | | | |
27.1054 + | STARTTLS | Transport layer security | [NNTP-TLS] |
27.1055 + | | | |
27.1056 + | STREAMING | Streaming feeds | [NNTP-STREAM] |
27.1057 + | | | |
27.1058 + | VERSION | Supported NNTP versions | Section 3.3.2 |
27.1059 + +-------------------+--------------------------+--------------------+
27.1060 +
27.1061 +
27.1062 +
27.1063 +
27.1064 +Feather Standards Track [Page 19]
27.1065 +
27.1066 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1067 +
27.1068 +
27.1069 +3.4. Mandatory and Optional Commands
27.1070 +
27.1071 + For a number of reasons, not all the commands in this specification
27.1072 + are mandatory. However, it is equally undesirable for every command
27.1073 + to be optional, since this means that a client will have no idea what
27.1074 + facilities are available. Therefore, as a compromise, some of the
27.1075 + commands in this specification are mandatory (they must be supported
27.1076 + by all servers) while the remainder are not. The latter are then
27.1077 + subdivided into bundles, each indicated by a single capability label.
27.1078 +
27.1079 + o If the label is included in the capability list returned by the
27.1080 + server, the server MUST support all commands in that bundle.
27.1081 +
27.1082 + o If the label is not included, the server MAY support none or some
27.1083 + of the commands but SHOULD NOT support all of them. In general,
27.1084 + there will be no way for a client to determine which commands are
27.1085 + supported without trying them.
27.1086 +
27.1087 + The bundles have been chosen to provide useful functionality, and
27.1088 + therefore server authors are discouraged from implementing only part
27.1089 + of a bundle.
27.1090 +
27.1091 + The description of each command will either indicate that it is
27.1092 + mandatory, or will give, using the term "indicating capability", the
27.1093 + capability label indicating whether the bundle including this command
27.1094 + is available.
27.1095 +
27.1096 + Where a server does not implement a command, it MUST always generate
27.1097 + a 500 generic response code (or a 501 generic response code in the
27.1098 + case of a variant of a command depending on a second keyword where
27.1099 + the base command is recognised). Otherwise, the command MUST be
27.1100 + fully implemented as specified; a server MUST NOT only partially
27.1101 + implement any of the commands in this specification. (Client authors
27.1102 + should note that some servers not conforming to this specification
27.1103 + will return a 502 generic response code to some commands that are not
27.1104 + implemented.)
27.1105 +
27.1106 + Note: some commands have cases that require other commands to be used
27.1107 + first. If the former command is implemented but the latter is not,
27.1108 + the former MUST still generate the relevant specific response code.
27.1109 + For example, if ARTICLE (Section 6.2.1) is implemented but GROUP
27.1110 + (Section 6.1.1) is not, the correct response to "ARTICLE 1234"
27.1111 + remains 412.
27.1112 +
27.1113 +
27.1114 +
27.1115 +
27.1116 +
27.1117 +
27.1118 +
27.1119 +
27.1120 +Feather Standards Track [Page 20]
27.1121 +
27.1122 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1123 +
27.1124 +
27.1125 +3.4.1. Reading and Transit Servers
27.1126 +
27.1127 + NNTP is traditionally used in two different ways. The first use is
27.1128 + "reading", where the client fetches articles from a large store
27.1129 + maintained by the server for immediate or later presentation to a
27.1130 + user and sends articles created by that user back to the server (an
27.1131 + action called "posting") to be stored and distributed to other stores
27.1132 + and users. The second use is for the bulk transfer of articles from
27.1133 + one store to another. Since the hosts making this transfer tend to
27.1134 + be peers in a network that transmit articles among one another, and
27.1135 + not end-user systems, this process is called "peering" or "transit".
27.1136 + (Even so, one host is still the client and the other is the server).
27.1137 +
27.1138 + In practice, these two uses are so different that some server
27.1139 + implementations are optimised for reading or for transit and, as a
27.1140 + result, do not offer the other facility or only offer limited
27.1141 + features. Other implementations are more general and offer both.
27.1142 + This specification allows for this by bundling the relevant commands
27.1143 + accordingly: the IHAVE command is designed for transit, while the
27.1144 + commands indicated by the READER capability are designed for reading
27.1145 + clients.
27.1146 +
27.1147 + Except as an effect of the MODE READER command (Section 5.3) on a
27.1148 + mode-switching server, once a server advertises either or both of the
27.1149 + IHAVE or READER capabilities, it MUST continue to advertise them for
27.1150 + the entire session.
27.1151 +
27.1152 + A server MAY provide different modes of behaviour (transit, reader,
27.1153 + or a combination) to different client connections and MAY use
27.1154 + external information, such as the IP address of the client, to
27.1155 + determine which mode to provide to any given connection.
27.1156 +
27.1157 + The official TCP port for the NNTP service is 119. However, if a
27.1158 + host wishes to offer separate servers for transit and reading
27.1159 + clients, port 433 SHOULD be used for the transit server and 119 for
27.1160 + the reading server.
27.1161 +
27.1162 +3.4.2. Mode Switching
27.1163 +
27.1164 + An implementation MAY, but SHOULD NOT, provide both transit and
27.1165 + reader facilities on the same server but require the client to select
27.1166 + which it wishes to use. Such an arrangement is called a
27.1167 + "mode-switching" server.
27.1168 +
27.1169 +
27.1170 +
27.1171 +
27.1172 +
27.1173 +
27.1174 +
27.1175 +
27.1176 +Feather Standards Track [Page 21]
27.1177 +
27.1178 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1179 +
27.1180 +
27.1181 + A mode-switching server has two modes:
27.1182 +
27.1183 + o Transit mode, which applies after the initial connection.
27.1184 +
27.1185 + * It MUST advertise the MODE-READER capability.
27.1186 +
27.1187 + * It MUST NOT advertise the READER capability.
27.1188 +
27.1189 + However, the server MAY cease to advertise the MODE-READER
27.1190 + capability after the client uses any command except CAPABILITIES.
27.1191 +
27.1192 + o Reading mode, after a successful MODE READER command (see Section
27.1193 + 5.3).
27.1194 +
27.1195 + * It MUST NOT advertise the MODE-READER capability.
27.1196 +
27.1197 + * It MUST advertise the READER capability.
27.1198 +
27.1199 + * It MAY NOT advertise the IHAVE capability, even if it was
27.1200 + advertising it in transit mode.
27.1201 +
27.1202 + A client SHOULD only issue a MODE READER command to a server if it is
27.1203 + advertising the MODE-READER capability. If the server does not
27.1204 + support CAPABILITIES (and therefore does not conform to this
27.1205 + specification), the client MAY use the following heuristic:
27.1206 +
27.1207 + o If the client wishes to use any "reader" commands, it SHOULD use
27.1208 + the MODE READER command immediately after the initial connection.
27.1209 +
27.1210 + o Otherwise, it SHOULD NOT use the MODE READER command.
27.1211 +
27.1212 + In each case, it should be prepared for some commands to be
27.1213 + unavailable that would have been available if it had made the other
27.1214 + choice.
27.1215 +
27.1216 +3.5. Pipelining
27.1217 +
27.1218 + NNTP is designed to operate over a reliable bi-directional
27.1219 + connection, such as TCP. Therefore, if a command does not depend on
27.1220 + the response to the previous one, it should not matter if it is sent
27.1221 + before that response is received. Doing this is called "pipelining".
27.1222 + However, certain server implementations throw away all text received
27.1223 + from the client following certain commands before sending their
27.1224 + response. If this happens, pipelining will be affected because one
27.1225 + or more commands will have been ignored or misinterpreted, and the
27.1226 + client will be matching the wrong responses to each command. Since
27.1227 + there are significant benefits to pipelining, but also circumstances
27.1228 + where it is reasonable or common for servers to behave in the above
27.1229 +
27.1230 +
27.1231 +
27.1232 +Feather Standards Track [Page 22]
27.1233 +
27.1234 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1235 +
27.1236 +
27.1237 + manner, this document puts certain requirements on both clients and
27.1238 + servers.
27.1239 +
27.1240 + Except where stated otherwise, a client MAY use pipelining. That is,
27.1241 + it may send a command before receiving the response for the previous
27.1242 + command. The server MUST allow pipelining and MUST NOT throw away
27.1243 + any text received after a command. Irrespective of whether
27.1244 + pipelining is used, the server MUST process commands in the order
27.1245 + they are sent.
27.1246 +
27.1247 + If the specific description of a command says it "MUST NOT be
27.1248 + pipelined", that command MUST end any pipeline of commands. That is,
27.1249 + the client MUST NOT send any following command until it receives the
27.1250 + CRLF at the end of the response from the command. The server MAY
27.1251 + ignore any data received after the command and before the CRLF at the
27.1252 + end of the response is sent to the client.
27.1253 +
27.1254 + The initial connection must not be part of a pipeline; that is, the
27.1255 + client MUST NOT send any command until it receives the CRLF at the
27.1256 + end of the greeting.
27.1257 +
27.1258 + If the client uses blocking system calls to send commands, it MUST
27.1259 + ensure that the amount of text sent in pipelining does not cause a
27.1260 + deadlock between transmission and reception. The amount of text
27.1261 + involved will depend on window sizes in the transmission layer;
27.1262 + typically, it is 4k octets for TCP. (Since the server only sends
27.1263 + data in response to commands from the client, the converse problem
27.1264 + does not occur.)
27.1265 +
27.1266 +3.5.1. Examples
27.1267 +
27.1268 + Example of correct use of pipelining:
27.1269 +
27.1270 + [C] GROUP misc.test
27.1271 + [C] STAT
27.1272 + [C] NEXT
27.1273 + [S] 211 1234 3000234 3002322 misc.test
27.1274 + [S] 223 3000234 <45223423@example.com> retrieved
27.1275 + [S] 223 3000237 <668929@example.org> retrieved
27.1276 +
27.1277 + Example of incorrect use of pipelining (the MODE READER command may
27.1278 + not be pipelined):
27.1279 +
27.1280 + [C] MODE READER
27.1281 + [C] DATE
27.1282 + [C] NEXT
27.1283 + [S] 200 Server ready, posting allowed
27.1284 + [S] 223 3000237 <668929@example.org> retrieved
27.1285 +
27.1286 +
27.1287 +
27.1288 +Feather Standards Track [Page 23]
27.1289 +
27.1290 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1291 +
27.1292 +
27.1293 + The DATE command has been thrown away by the server, so there is no
27.1294 + 111 response to match it.
27.1295 +
27.1296 +3.6. Articles
27.1297 +
27.1298 + NNTP is intended to transfer articles between clients and servers.
27.1299 + For the purposes of this specification, articles are required to
27.1300 + conform to the rules in this section, and clients and servers MUST
27.1301 + correctly process any article received from the other that does so.
27.1302 + Note that this requirement applies only to the contents of
27.1303 + communications over NNTP; it does not prevent the client or server
27.1304 + from subsequently rejecting an article for reasons of local policy.
27.1305 + Also see Appendix A for further restrictions on the format of
27.1306 + articles in some uses of NNTP.
27.1307 +
27.1308 + An article consists of two parts: the headers and the body. They are
27.1309 + separated by a single empty line, or in other words by two
27.1310 + consecutive CRLF pairs (if there is more than one empty line, the
27.1311 + second and subsequent ones are part of the body). In order to meet
27.1312 + the general requirements of NNTP, an article MUST NOT include the
27.1313 + octet NUL, MUST NOT contain the octets LF and CR other than as part
27.1314 + of a CRLF pair, and MUST end with a CRLF pair. This specification
27.1315 + puts no further restrictions on the body; in particular, it MAY be
27.1316 + empty.
27.1317 +
27.1318 + The headers of an article consist of one or more header lines. Each
27.1319 + header line consists of a header name, a colon, a space, the header
27.1320 + content, and a CRLF, in that order. The name consists of one or more
27.1321 + printable US-ASCII characters other than colon and, for the purposes
27.1322 + of this specification, is not case sensitive. There MAY be more than
27.1323 + one header line with the same name. The content MUST NOT contain
27.1324 + CRLF; it MAY be empty. A header may be "folded"; that is, a CRLF
27.1325 + pair may be placed before any TAB or space in the line. There MUST
27.1326 + still be some other octet between any two CRLF pairs in a header
27.1327 + line. (Note that folding means that the header line occupies more
27.1328 + than one line when displayed or transmitted; nevertheless, it is
27.1329 + still referred to as "a" header line.) The presence or absence of
27.1330 + folding does not affect the meaning of the header line; that is, the
27.1331 + CRLF pairs introduced by folding are not considered part of the
27.1332 + header content. Header lines SHOULD NOT be folded before the space
27.1333 + after the colon that follows the header name and SHOULD include at
27.1334 + least one octet other than %x09 or %x20 between CRLF pairs. However,
27.1335 + if an article that fails to satisfy this requirement has been
27.1336 + received from elsewhere, clients and servers MAY transfer it to each
27.1337 + other without re-folding it.
27.1338 +
27.1339 +
27.1340 +
27.1341 +
27.1342 +
27.1343 +
27.1344 +Feather Standards Track [Page 24]
27.1345 +
27.1346 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1347 +
27.1348 +
27.1349 + The content of a header SHOULD be in UTF-8. However, if an
27.1350 + implementation receives an article from elsewhere that uses octets in
27.1351 + the range 128 to 255 in some other manner, it MAY pass it to a client
27.1352 + or server without modification. Therefore, implementations MUST be
27.1353 + prepared to receive such headers, and data derived from them (e.g.,
27.1354 + in the responses from the OVER command, Section 8.3), and MUST NOT
27.1355 + assume that they are always UTF-8. Any external processing of those
27.1356 + headers, including identifying the encoding used, is outside the
27.1357 + scope of this document.
27.1358 +
27.1359 + Each article MUST have a unique message-id; two articles offered by
27.1360 + an NNTP server MUST NOT have the same message-id. For the purposes
27.1361 + of this specification, message-ids are opaque strings that MUST meet
27.1362 + the following requirements:
27.1363 +
27.1364 + o A message-id MUST begin with "<", end with ">", and MUST NOT
27.1365 + contain the latter except at the end.
27.1366 +
27.1367 + o A message-id MUST be between 3 and 250 octets in length.
27.1368 +
27.1369 + o A message-id MUST NOT contain octets other than printable US-ASCII
27.1370 + characters.
27.1371 +
27.1372 + Two message-ids are the same if and only if they consist of the same
27.1373 + sequence of octets.
27.1374 +
27.1375 + This specification does not describe how the message-id of an article
27.1376 + is determined. If the server does not have any way to determine a
27.1377 + message-id from the article itself, it MUST synthesize one (this
27.1378 + specification does not require that the article be changed as a
27.1379 + result). See also Appendix A.2.
27.1380 +
27.1381 +4. The WILDMAT Format
27.1382 +
27.1383 + The WILDMAT format described here is based on the version first
27.1384 + developed by Rich Salz [SALZ1992], which was in turn derived from the
27.1385 + format used in the UNIX "find" command to articulate file names. It
27.1386 + was developed to provide a uniform mechanism for matching patterns in
27.1387 + the same manner that the UNIX shell matches filenames.
27.1388 +
27.1389 +
27.1390 +
27.1391 +
27.1392 +
27.1393 +
27.1394 +
27.1395 +
27.1396 +
27.1397 +
27.1398 +
27.1399 +
27.1400 +Feather Standards Track [Page 25]
27.1401 +
27.1402 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1403 +
27.1404 +
27.1405 +4.1. Wildmat Syntax
27.1406 +
27.1407 + A wildmat is described by the following ABNF [RFC4234] syntax, which
27.1408 + is an extract of that in Section 9.8.
27.1409 +
27.1410 + wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
27.1411 + wildmat-pattern = 1*wildmat-item
27.1412 + wildmat-item = wildmat-exact / wildmat-wild
27.1413 + wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
27.1414 + UTF8-non-ascii ; exclude ! * , ? [ \ ]
27.1415 + wildmat-wild = "*" / "?"
27.1416 +
27.1417 + Note: the characters ",", "\", "[", and "]" are not allowed in
27.1418 + wildmats, while * and ? are always wildcards. This should not be a
27.1419 + problem, since these characters cannot occur in newsgroup names,
27.1420 + which is the only current use of wildmats. Backslash is commonly
27.1421 + used to suppress the special meaning of characters, whereas brackets
27.1422 + are used to introduce sets. However, these usages are not universal,
27.1423 + and interpretation of these characters in the context of UTF-8
27.1424 + strings is potentially complex and differs from existing practice, so
27.1425 + they were omitted from this specification. A future extension to
27.1426 + this specification may provide semantics for these characters.
27.1427 +
27.1428 +4.2. Wildmat Semantics
27.1429 +
27.1430 + A wildmat is tested against a string and either matches or does not
27.1431 + match. To do this, each constituent <wildmat-pattern> is matched
27.1432 + against the string, and the rightmost pattern that matches is
27.1433 + identified. If that <wildmat-pattern> is not preceded with "!", the
27.1434 + whole wildmat matches. If it is preceded by "!", or if no <wildmat-
27.1435 + pattern> matches, the whole wildmat does not match.
27.1436 +
27.1437 + For example, consider the wildmat "a*,!*b,*c*":
27.1438 +
27.1439 + o The string "aaa" matches because the rightmost match is with "a*".
27.1440 +
27.1441 + o The string "abb" does not match because the rightmost match is
27.1442 + with "*b".
27.1443 +
27.1444 + o The string "ccb" matches because the rightmost match is with
27.1445 + "*c*".
27.1446 +
27.1447 + o The string "xxx" does not match because no <wildmat-pattern>
27.1448 + matches.
27.1449 +
27.1450 + A <wildmat-pattern> matches a string if the string can be broken into
27.1451 + components, each of which matches the corresponding <wildmat-item> in
27.1452 + the pattern. The matches must be in the same order, and the whole
27.1453 +
27.1454 +
27.1455 +
27.1456 +Feather Standards Track [Page 26]
27.1457 +
27.1458 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1459 +
27.1460 +
27.1461 + string must be used in the match. The pattern is "anchored"; that
27.1462 + is, the first and last characters in the string must match the first
27.1463 + and last item, respectively (unless that item is an asterisk matching
27.1464 + zero characters).
27.1465 +
27.1466 + A <wildmat-exact> matches the same character (which may be more than
27.1467 + one octet in UTF-8).
27.1468 +
27.1469 + "?" matches exactly one character (which may be more than one octet).
27.1470 +
27.1471 + "*" matches zero or more characters. It can match an empty string,
27.1472 + but it cannot match a subsequence of a UTF-8 sequence that is not
27.1473 + aligned to the character boundaries.
27.1474 +
27.1475 +4.3. Extensions
27.1476 +
27.1477 + An NNTP server or extension MAY extend the syntax or semantics of
27.1478 + wildmats provided that all wildmats that meet the requirements of
27.1479 + Section 4.1 have the meaning ascribed to them by Section 4.2. Future
27.1480 + editions of this document may also extend wildmats.
27.1481 +
27.1482 +4.4. Examples
27.1483 +
27.1484 + In these examples, $ and @ are used to represent the two octets %xC2
27.1485 + and %xA3, respectively; $@ is thus the UTF-8 encoding for the pound
27.1486 + sterling symbol, shown as # in the descriptions.
27.1487 +
27.1488 + Wildmat Description of strings that match
27.1489 + abc The one string "abc"
27.1490 + abc,def The two strings "abc" and "def"
27.1491 + $@ The one character string "#"
27.1492 + a* Any string that begins with "a"
27.1493 + a*b Any string that begins with "a" and ends with "b"
27.1494 + a*,*b Any string that begins with "a" or ends with "b"
27.1495 + a*,!*b Any string that begins with "a" and does not end with
27.1496 + "b"
27.1497 + a*,!*b,c* Any string that begins with "a" and does not end with
27.1498 + "b", and any string that begins with "c" no matter
27.1499 + what it ends with
27.1500 + a*,c*,!*b Any string that begins with "a" or "c" and does not
27.1501 + end with "b"
27.1502 + ?a* Any string with "a" as its second character
27.1503 + ??a* Any string with "a" as its third character
27.1504 + *a? Any string with "a" as its penultimate character
27.1505 + *a?? Any string with "a" as its antepenultimate character
27.1506 +
27.1507 +
27.1508 +
27.1509 +
27.1510 +
27.1511 +
27.1512 +Feather Standards Track [Page 27]
27.1513 +
27.1514 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1515 +
27.1516 +
27.1517 +5. Session Administration Commands
27.1518 +
27.1519 +5.1. Initial Connection
27.1520 +
27.1521 +5.1.1. Usage
27.1522 +
27.1523 + This command MUST NOT be pipelined.
27.1524 +
27.1525 + Responses [1]
27.1526 + 200 Service available, posting allowed
27.1527 + 201 Service available, posting prohibited
27.1528 + 400 Service temporarily unavailable [2]
27.1529 + 502 Service permanently unavailable [2]
27.1530 +
27.1531 + [1] These are the only valid response codes for the initial greeting;
27.1532 + the server MUST not return any other generic response code.
27.1533 +
27.1534 + [2] Following a 400 or 502 response, the server MUST immediately
27.1535 + close the connection.
27.1536 +
27.1537 +5.1.2. Description
27.1538 +
27.1539 + There is no command presented by the client upon initial connection
27.1540 + to the server. The server MUST present an appropriate response code
27.1541 + as a greeting to the client. This response informs the client
27.1542 + whether service is available and whether the client is permitted to
27.1543 + post.
27.1544 +
27.1545 + If the server will accept further commands from the client including
27.1546 + POST, the server MUST present a 200 greeting code. If the server
27.1547 + will accept further commands from the client, but the client is not
27.1548 + authorized to post articles using the POST command, the server MUST
27.1549 + present a 201 greeting code.
27.1550 +
27.1551 + Otherwise, the server MUST present a 400 or 502 greeting code and
27.1552 + then immediately close the connection. 400 SHOULD be used if the
27.1553 + issue is only temporary (for example, because of load) and the client
27.1554 + can expect to be able to connect successfully at some point in the
27.1555 + future without making any changes. 502 MUST be used if the client is
27.1556 + not permitted under any circumstances to interact with the server,
27.1557 + and MAY be used if the server has insufficient information to
27.1558 + determine whether the issue is temporary or permanent.
27.1559 +
27.1560 + Note: the distinction between the 200 and 201 response codes has
27.1561 + turned out in practice to be insufficient; for example, some servers
27.1562 + do not allow posting until the client has authenticated, while other
27.1563 + clients assume that a 201 response means that posting will never be
27.1564 + possible even after authentication. Therefore, clients SHOULD use
27.1565 +
27.1566 +
27.1567 +
27.1568 +Feather Standards Track [Page 28]
27.1569 +
27.1570 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1571 +
27.1572 +
27.1573 + the CAPABILITIES command (Section 5.2) rather than rely on this
27.1574 + response.
27.1575 +
27.1576 +5.1.3. Examples
27.1577 +
27.1578 + Example of a normal connection from an authorized client that then
27.1579 + terminates the session (see Section 5.4):
27.1580 +
27.1581 + [Initial connection set-up completed.]
27.1582 + [S] 200 NNTP Service Ready, posting permitted
27.1583 + [C] QUIT
27.1584 + [S] 205 NNTP Service exits normally
27.1585 + [Server closes connection.]
27.1586 +
27.1587 + Example of a normal connection from an authorized client that is not
27.1588 + permitted to post, which also immediately terminates the session:
27.1589 +
27.1590 + [Initial connection set-up completed.]
27.1591 + [S] 201 NNTP Service Ready, posting prohibited
27.1592 + [C] QUIT
27.1593 + [S] 205 NNTP Service exits normally
27.1594 + [Server closes connection.]
27.1595 +
27.1596 + Example of a normal connection from an unauthorized client:
27.1597 +
27.1598 + [Initial connection set-up completed.]
27.1599 + [S] 502 NNTP Service permanently unavailable
27.1600 + [Server closes connection.]
27.1601 +
27.1602 + Example of a connection from a client if the server is unable to
27.1603 + provide service:
27.1604 +
27.1605 + [Initial connection set-up completed.]
27.1606 + [S] 400 NNTP Service temporarily unavailable
27.1607 + [Server closes connection.]
27.1608 +
27.1609 +5.2. CAPABILITIES
27.1610 +
27.1611 +5.2.1. Usage
27.1612 +
27.1613 + This command is mandatory.
27.1614 +
27.1615 + Syntax
27.1616 + CAPABILITIES [keyword]
27.1617 +
27.1618 + Responses
27.1619 + 101 Capability list follows (multi-line)
27.1620 +
27.1621 +
27.1622 +
27.1623 +
27.1624 +Feather Standards Track [Page 29]
27.1625 +
27.1626 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1627 +
27.1628 +
27.1629 + Parameters
27.1630 + keyword additional feature, see description
27.1631 +
27.1632 +5.2.2. Description
27.1633 +
27.1634 + The CAPABILITIES command allows a client to determine the
27.1635 + capabilities of the server at any given time.
27.1636 +
27.1637 + This command MAY be issued at any time; the server MUST NOT require
27.1638 + it to be issued in order to make use of any capability. The response
27.1639 + generated by this command MAY change during a session because of
27.1640 + other state information (which, in turn, may be changed by the
27.1641 + effects of other commands or by external events). An NNTP client is
27.1642 + only able to get the current and correct information concerning
27.1643 + available capabilities at any point during a session by issuing a
27.1644 + CAPABILITIES command at that point of that session and processing the
27.1645 + response.
27.1646 +
27.1647 + The capability list is returned as a multi-line data block following
27.1648 + the 101 response code. Each capability is described by a separate
27.1649 + capability line. The server MUST NOT list the same capability twice
27.1650 + in the response, even with different arguments. Except that the
27.1651 + VERSION capability MUST be the first line, the order in which the
27.1652 + capability lines appears is not significant; the server need not even
27.1653 + consistently return the same order.
27.1654 +
27.1655 + While some capabilities are likely to be always available or never
27.1656 + available, others (notably extensions) will appear and disappear
27.1657 + depending on server state changes within the session or on external
27.1658 + events between sessions. An NNTP client MAY cache the results of
27.1659 + this command, but MUST NOT rely on the correctness of any cached
27.1660 + results, whether from earlier in this session or from a previous
27.1661 + session, MUST cope gracefully with the cached status being out of
27.1662 + date, and SHOULD (if caching results) provide a way to force the
27.1663 + cached information to be refreshed. Furthermore, a client MUST NOT
27.1664 + use cached results in relation to security, privacy, and
27.1665 + authentication extensions. See Section 12.6 for further discussion
27.1666 + of this topic.
27.1667 +
27.1668 + The keyword argument is not used by this specification. It is
27.1669 + provided so that extensions or revisions to this specification can
27.1670 + include extra features for this command without requiring the
27.1671 + CAPABILITIES command to be used twice (once to determine if the extra
27.1672 + features are available, and a second time to make use of them). If
27.1673 + the server does not recognise the argument (and it is a keyword), it
27.1674 + MUST respond with the 101 response code as if the argument had been
27.1675 + omitted. If an argument is provided that the server does recognise,
27.1676 + it MAY use the 101 response code or MAY use some other response code
27.1677 +
27.1678 +
27.1679 +
27.1680 +Feather Standards Track [Page 30]
27.1681 +
27.1682 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1683 +
27.1684 +
27.1685 + (which will be defined in the specification of that feature). If the
27.1686 + argument is not a keyword, the 501 generic response code MUST be
27.1687 + returned. The server MUST NOT generate any other response code to
27.1688 + the CAPABILITIES command.
27.1689 +
27.1690 +5.2.3. Examples
27.1691 +
27.1692 + Example of a minimal response (a read-only server):
27.1693 +
27.1694 + [C] CAPABILITIES
27.1695 + [S] 101 Capability list:
27.1696 + [S] VERSION 2
27.1697 + [S] READER
27.1698 + [S] LIST ACTIVE NEWSGROUPS
27.1699 + [S] .
27.1700 +
27.1701 + Example of a response from a server that has a range of facilities
27.1702 + and that also describes itself:
27.1703 +
27.1704 + [C] CAPABILITIES
27.1705 + [S] 101 Capability list:
27.1706 + [S] VERSION 2
27.1707 + [S] READER
27.1708 + [S] IHAVE
27.1709 + [S] POST
27.1710 + [S] NEWNEWS
27.1711 + [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT
27.1712 + [S] IMPLEMENTATION INN 4.2 2004-12-25
27.1713 + [S] OVER MSGID
27.1714 + [S] STREAMING
27.1715 + [S] XSECRET
27.1716 + [S] .
27.1717 +
27.1718 + Example of a server that supports more than one version of NNTP:
27.1719 +
27.1720 + [C] CAPABILITIES
27.1721 + [S] 101 Capability list:
27.1722 + [S] VERSION 2 3
27.1723 + [S] READER
27.1724 + [S] LIST ACTIVE NEWSGROUPS
27.1725 + [S] .
27.1726 +
27.1727 +
27.1728 +
27.1729 +
27.1730 +
27.1731 +
27.1732 +
27.1733 +
27.1734 +
27.1735 +
27.1736 +Feather Standards Track [Page 31]
27.1737 +
27.1738 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1739 +
27.1740 +
27.1741 + Example of a client attempting to use a feature of the CAPABILITIES
27.1742 + command that the server does not support:
27.1743 +
27.1744 + [C] CAPABILITIES AUTOUPDATE
27.1745 + [S] 101 Capability list:
27.1746 + [S] VERSION 2
27.1747 + [S] READER
27.1748 + [S] IHAVE
27.1749 + [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS
27.1750 + [S] OVER MSGID
27.1751 + [S] HDR
27.1752 + [S] NEWNEWS
27.1753 + [S] .
27.1754 +
27.1755 +5.3. MODE READER
27.1756 +
27.1757 +5.3.1. Usage
27.1758 +
27.1759 + Indicating capability: MODE-READER
27.1760 +
27.1761 + This command MUST NOT be pipelined.
27.1762 +
27.1763 + Syntax
27.1764 + MODE READER
27.1765 +
27.1766 + Responses
27.1767 + 200 Posting allowed
27.1768 + 201 Posting prohibited
27.1769 + 502 Reading service permanently unavailable [1]
27.1770 +
27.1771 + [1] Following a 502 response the server MUST immediately close the
27.1772 + connection.
27.1773 +
27.1774 +5.3.2. Description
27.1775 +
27.1776 + The MODE READER command instructs a mode-switching server to switch
27.1777 + modes, as described in Section 3.4.2.
27.1778 +
27.1779 + If the server is mode-switching, it switches from its transit mode to
27.1780 + its reader mode, indicating this by changing the capability list
27.1781 + accordingly. It MUST then return a 200 or 201 response with the same
27.1782 + meaning as for the initial greeting (as described in Section 5.1.1).
27.1783 + Note that the response need not be the same as that presented during
27.1784 + the initial greeting. The client MUST NOT issue MODE READER more
27.1785 + than once in a session or after any security or privacy commands are
27.1786 + issued. When the MODE READER command is issued, the server MAY reset
27.1787 + its state to that immediately after the initial connection before
27.1788 + switching mode.
27.1789 +
27.1790 +
27.1791 +
27.1792 +Feather Standards Track [Page 32]
27.1793 +
27.1794 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1795 +
27.1796 +
27.1797 + If the server is not mode-switching, then the following apply:
27.1798 +
27.1799 + o If it advertises the READER capability, it MUST return a 200 or
27.1800 + 201 response with the same meaning as for the initial greeting; in
27.1801 + this case, the command MUST NOT affect the server state in any
27.1802 + way.
27.1803 +
27.1804 + o If it does not advertise the READER capability, it MUST return a
27.1805 + 502 response and then immediately close the connection.
27.1806 +
27.1807 +5.3.3. Examples
27.1808 +
27.1809 + Example of use of the MODE READER command on a transit-only server
27.1810 + (which therefore does not providing reading facilities):
27.1811 +
27.1812 + [C] CAPABILITIES
27.1813 + [S] 101 Capability list:
27.1814 + [S] VERSION 2
27.1815 + [S] IHAVE
27.1816 + [S] .
27.1817 + [C] MODE READER
27.1818 + [S] 502 Transit service only
27.1819 + [Server closes connection.]
27.1820 +
27.1821 + Example of use of the MODE READER command on a server that provides
27.1822 + reading facilities:
27.1823 +
27.1824 + [C] CAPABILITIES
27.1825 + [S] 101 Capability list:
27.1826 + [S] VERSION 2
27.1827 + [S] READER
27.1828 + [S] LIST ACTIVE NEWSGROUPS
27.1829 + [S] .
27.1830 + [C] MODE READER
27.1831 + [S] 200 Reader mode, posting permitted
27.1832 + [C] IHAVE <i.am.an.article.you.have@example.com>
27.1833 + [S] 500 Permission denied
27.1834 + [C] GROUP misc.test
27.1835 + [S] 211 1234 3000234 3002322 misc.test
27.1836 +
27.1837 + Note that in both of these situations, the client SHOULD NOT use MODE
27.1838 + READER.
27.1839 +
27.1840 +
27.1841 +
27.1842 +
27.1843 +
27.1844 +
27.1845 +
27.1846 +
27.1847 +
27.1848 +Feather Standards Track [Page 33]
27.1849 +
27.1850 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1851 +
27.1852 +
27.1853 + Example of use of the MODE READER command on a mode-switching server:
27.1854 +
27.1855 + [C] CAPABILITIES
27.1856 + [S] 101 Capability list:
27.1857 + [S] VERSION 2
27.1858 + [S] IHAVE
27.1859 + [S] MODE-READER
27.1860 + [S] .
27.1861 + [C] MODE READER
27.1862 + [S] 200 Reader mode, posting permitted
27.1863 + [C] CAPABILITIES
27.1864 + [S] 101 Capability list:
27.1865 + [S] VERSION 2
27.1866 + [S] READER
27.1867 + [S] NEWNEWS
27.1868 + [S] LIST ACTIVE NEWSGROUPS
27.1869 + [S] STARTTLS
27.1870 + [S] .
27.1871 +
27.1872 + In this case, the server offers (but does not require) TLS privacy in
27.1873 + its reading mode but not in its transit mode.
27.1874 +
27.1875 + Example of use of the MODE READER command where the client is not
27.1876 + permitted to post:
27.1877 +
27.1878 + [C] MODE READER
27.1879 + [S] 201 NNTP Service Ready, posting prohibited
27.1880 +
27.1881 +5.4. QUIT
27.1882 +
27.1883 +5.4.1. Usage
27.1884 +
27.1885 + This command is mandatory.
27.1886 +
27.1887 + Syntax
27.1888 + QUIT
27.1889 +
27.1890 + Responses
27.1891 + 205 Connection closing
27.1892 +
27.1893 +5.4.2. Description
27.1894 +
27.1895 + The client uses the QUIT command to terminate the session. The
27.1896 + server MUST acknowledge the QUIT command and then close the
27.1897 + connection to the client. This is the preferred method for a client
27.1898 + to indicate that it has finished all of its transactions with the
27.1899 + NNTP server.
27.1900 +
27.1901 +
27.1902 +
27.1903 +
27.1904 +Feather Standards Track [Page 34]
27.1905 +
27.1906 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1907 +
27.1908 +
27.1909 + If a client simply disconnects (or if the connection times out or
27.1910 + some other fault occurs), the server MUST gracefully cease its
27.1911 + attempts to service the client, disconnecting from its end if
27.1912 + necessary.
27.1913 +
27.1914 + The server MUST NOT generate any response code to the QUIT command
27.1915 + other than 205 or, if any arguments are provided, 501.
27.1916 +
27.1917 +5.4.3. Examples
27.1918 +
27.1919 + [C] QUIT
27.1920 + [S] 205 closing connection
27.1921 + [Server closes connection.]
27.1922 +
27.1923 +6. Article Posting and Retrieval
27.1924 +
27.1925 + News-reading clients have available a variety of mechanisms to
27.1926 + retrieve articles via NNTP. The news articles are stored and indexed
27.1927 + using three types of keys. The first type of key is the message-id
27.1928 + of an article and is globally unique. The second type of key is
27.1929 + composed of a newsgroup name and an article number within that
27.1930 + newsgroup. On a particular server, there MUST only be one article
27.1931 + with a given number within any newsgroup, and an article MUST NOT
27.1932 + have two different numbers in the same newsgroup. An article can be
27.1933 + cross-posted to multiple newsgroups, so there may be multiple keys
27.1934 + that point to the same article on the same server; these MAY have
27.1935 + different numbers in each newsgroup. However, this type of key is
27.1936 + not required to be globally unique, so the same key MAY refer to
27.1937 + different articles on different servers. (Note that the terms
27.1938 + "group" and "newsgroup" are equivalent.)
27.1939 +
27.1940 + The final type of key is the arrival timestamp, giving the time that
27.1941 + the article arrived at the server. The server MUST ensure that
27.1942 + article numbers are issued in order of arrival timestamp; that is,
27.1943 + articles arriving later MUST have higher numbers than those that
27.1944 + arrive earlier. The server SHOULD allocate the next sequential
27.1945 + unused number to each new article.
27.1946 +
27.1947 + Article numbers MUST lie between 1 and 2,147,483,647, inclusive. The
27.1948 + client and server MAY use leading zeroes in specifying article
27.1949 + numbers but MUST NOT use more than 16 digits. In some situations,
27.1950 + the value zero replaces an article number to show some special
27.1951 + situation.
27.1952 +
27.1953 + Note that it is likely that the article number limit of 2,147,483,647
27.1954 + will be increased by a future revision or extension to this
27.1955 + specification. While servers MUST NOT send article numbers greater
27.1956 + than this current limit, client and server developers are advised to
27.1957 +
27.1958 +
27.1959 +
27.1960 +Feather Standards Track [Page 35]
27.1961 +
27.1962 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.1963 +
27.1964 +
27.1965 + use internal structures and datatypes capable of handling larger
27.1966 + values in anticipation of such a change.
27.1967 +
27.1968 +6.1. Group and Article Selection
27.1969 +
27.1970 + The following commands are used to set the "currently selected
27.1971 + newsgroup" and the "current article number", which are used by
27.1972 + various commands. At the start of an NNTP session, both of these
27.1973 + values are set to the special value "invalid".
27.1974 +
27.1975 +6.1.1. GROUP
27.1976 +
27.1977 +6.1.1.1. Usage
27.1978 +
27.1979 + Indicating capability: READER
27.1980 +
27.1981 + Syntax
27.1982 + GROUP group
27.1983 +
27.1984 + Responses
27.1985 + 211 number low high group Group successfully selected
27.1986 + 411 No such newsgroup
27.1987 +
27.1988 + Parameters
27.1989 + group Name of newsgroup
27.1990 + number Estimated number of articles in the group
27.1991 + low Reported low water mark
27.1992 + high Reported high water mark
27.1993 +
27.1994 +6.1.1.2. Description
27.1995 +
27.1996 + The GROUP command selects a newsgroup as the currently selected
27.1997 + newsgroup and returns summary information about it.
27.1998 +
27.1999 + The required argument is the name of the newsgroup to be selected
27.2000 + (e.g., "news.software.nntp"). A list of valid newsgroups may be
27.2001 + obtained by using the LIST ACTIVE command (see Section 7.6.3).
27.2002 +
27.2003 + The successful selection response will return the article numbers of
27.2004 + the first and last articles in the group at the moment of selection
27.2005 + (these numbers are referred to as the "reported low water mark" and
27.2006 + the "reported high water mark") and an estimate of the number of
27.2007 + articles in the group currently available.
27.2008 +
27.2009 + If the group is not empty, the estimate MUST be at least the actual
27.2010 + number of articles available and MUST be no greater than one more
27.2011 + than the difference between the reported low and high water marks.
27.2012 + (Some implementations will actually count the number of articles
27.2013 +
27.2014 +
27.2015 +
27.2016 +Feather Standards Track [Page 36]
27.2017 +
27.2018 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2019 +
27.2020 +
27.2021 + currently stored. Others will just subtract the low water mark from
27.2022 + the high water mark and add one to get an estimate.)
27.2023 +
27.2024 + If the group is empty, one of the following three situations will
27.2025 + occur. Clients MUST accept all three cases; servers MUST NOT
27.2026 + represent an empty group in any other way.
27.2027 +
27.2028 + o The high water mark will be one less than the low water mark, and
27.2029 + the estimated article count will be zero. Servers SHOULD use this
27.2030 + method to show an empty group. This is the only time that the
27.2031 + high water mark can be less than the low water mark.
27.2032 +
27.2033 + o All three numbers will be zero.
27.2034 +
27.2035 + o The high water mark is greater than or equal to the low water
27.2036 + mark. The estimated article count might be zero or non-zero; if
27.2037 + it is non-zero, the same requirements apply as for a non-empty
27.2038 + group.
27.2039 +
27.2040 + The set of articles in a group may change after the GROUP command is
27.2041 + carried out:
27.2042 +
27.2043 + o Articles may be removed from the group.
27.2044 +
27.2045 + o Articles may be reinstated in the group with the same article
27.2046 + number, but those articles MUST have numbers no less than the
27.2047 + reported low water mark (note that this is a reinstatement of the
27.2048 + previous article, not a new article reusing the number).
27.2049 +
27.2050 + o New articles may be added with article numbers greater than the
27.2051 + reported high water mark. (If an article that was the one with
27.2052 + the highest number has been removed and the high water mark has
27.2053 + been adjusted accordingly, the next new article will not have the
27.2054 + number one greater than the reported high water mark.)
27.2055 +
27.2056 + Except when the group is empty and all three numbers are zero,
27.2057 + whenever a subsequent GROUP command for the same newsgroup is issued,
27.2058 + either by the same client or a different client, the reported low
27.2059 + water mark in the response MUST be no less than that in any previous
27.2060 + response for that newsgroup in this session, and it SHOULD be no less
27.2061 + than that in any previous response for that newsgroup ever sent to
27.2062 + any client. Any failure to meet the latter condition SHOULD be
27.2063 + transient only. The client may make use of the low water mark to
27.2064 + remove all remembered information about articles with lower numbers,
27.2065 + as these will never recur. This includes the situation when the high
27.2066 + water mark is one less than the low water mark. No similar
27.2067 + assumption can be made about the high water mark, as this can
27.2068 +
27.2069 +
27.2070 +
27.2071 +
27.2072 +Feather Standards Track [Page 37]
27.2073 +
27.2074 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2075 +
27.2076 +
27.2077 + decrease if an article is removed and then increase again if it is
27.2078 + reinstated or if new articles arrive.
27.2079 +
27.2080 + When a valid group is selected by means of this command, the
27.2081 + currently selected newsgroup MUST be set to that group, and the
27.2082 + current article number MUST be set to the first article in the group
27.2083 + (this applies even if the group is already the currently selected
27.2084 + newsgroup). If an empty newsgroup is selected, the current article
27.2085 + number is made invalid. If an invalid group is specified, the
27.2086 + currently selected newsgroup and current article number MUST NOT be
27.2087 + changed.
27.2088 +
27.2089 + The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a
27.2090 + client, and a successful response received, before any other command
27.2091 + is used that depends on the value of the currently selected newsgroup
27.2092 + or current article number.
27.2093 +
27.2094 + If the group specified is not available on the server, a 411 response
27.2095 + MUST be returned.
27.2096 +
27.2097 +6.1.1.3. Examples
27.2098 +
27.2099 + Example for a group known to the server:
27.2100 +
27.2101 + [C] GROUP misc.test
27.2102 + [S] 211 1234 3000234 3002322 misc.test
27.2103 +
27.2104 + Example for a group unknown to the server:
27.2105 +
27.2106 + [C] GROUP example.is.sob.bradner.or.barber
27.2107 + [S] 411 example.is.sob.bradner.or.barber is unknown
27.2108 +
27.2109 + Example of an empty group using the preferred response:
27.2110 +
27.2111 + [C] GROUP example.currently.empty.newsgroup
27.2112 + [S] 211 0 4000 3999 example.currently.empty.newsgroup
27.2113 +
27.2114 + Example of an empty group using an alternative response:
27.2115 +
27.2116 + [C] GROUP example.currently.empty.newsgroup
27.2117 + [S] 211 0 0 0 example.currently.empty.newsgroup
27.2118 +
27.2119 + Example of an empty group using a different alternative response:
27.2120 +
27.2121 + [C] GROUP example.currently.empty.newsgroup
27.2122 + [S] 211 0 4000 4321 example.currently.empty.newsgroup
27.2123 +
27.2124 +
27.2125 +
27.2126 +
27.2127 +
27.2128 +Feather Standards Track [Page 38]
27.2129 +
27.2130 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2131 +
27.2132 +
27.2133 + Example reselecting the currently selected newsgroup:
27.2134 +
27.2135 + [C] GROUP misc.test
27.2136 + [S] 211 1234 234 567 misc.test
27.2137 + [C] STAT 444
27.2138 + [S] 223 444 <123456@example.net> retrieved
27.2139 + [C] GROUP misc.test
27.2140 + [S] 211 1234 234 567 misc.test
27.2141 + [C] STAT
27.2142 + [S] 223 234 <different@example.net> retrieved
27.2143 +
27.2144 +6.1.2. LISTGROUP
27.2145 +
27.2146 +6.1.2.1. Usage
27.2147 +
27.2148 + Indicating capability: READER
27.2149 +
27.2150 + Syntax
27.2151 + LISTGROUP [group [range]]
27.2152 +
27.2153 + Responses
27.2154 + 211 number low high group Article numbers follow (multi-line)
27.2155 + 411 No such newsgroup
27.2156 + 412 No newsgroup selected [1]
27.2157 +
27.2158 + Parameters
27.2159 + group Name of newsgroup
27.2160 + range Range of articles to report
27.2161 + number Estimated number of articles in the group
27.2162 + low Reported low water mark
27.2163 + high Reported high water mark
27.2164 +
27.2165 + [1] The 412 response can only occur if no group has been specified.
27.2166 +
27.2167 +6.1.2.2. Description
27.2168 +
27.2169 + The LISTGROUP command selects a newsgroup in the same manner as the
27.2170 + GROUP command (see Section 6.1.1) but also provides a list of article
27.2171 + numbers in the newsgroup. If no group is specified, the currently
27.2172 + selected newsgroup is used.
27.2173 +
27.2174 + On success, a list of article numbers is returned as a multi-line
27.2175 + data block following the 211 response code (the arguments on the
27.2176 + initial response line are the same as for the GROUP command). The
27.2177 + list contains one number per line and is in numerical order. It
27.2178 + lists precisely those articles that exist in the group at the moment
27.2179 + of selection (therefore, an empty group produces an empty list). If
27.2180 + the optional range argument is specified, only articles within the
27.2181 +
27.2182 +
27.2183 +
27.2184 +Feather Standards Track [Page 39]
27.2185 +
27.2186 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2187 +
27.2188 +
27.2189 + range are included in the list (therefore, the list MAY be empty even
27.2190 + if the group is not).
27.2191 +
27.2192 + The range argument may be any of the following:
27.2193 +
27.2194 + o An article number.
27.2195 +
27.2196 + o An article number followed by a dash to indicate all following.
27.2197 +
27.2198 + o An article number followed by a dash followed by another article
27.2199 + number.
27.2200 +
27.2201 + In the last case, if the second number is less than the first number,
27.2202 + then the range contains no articles. Omitting the range is
27.2203 + equivalent to the range 1- being specified.
27.2204 +
27.2205 + If the group specified is not available on the server, a 411 response
27.2206 + MUST be returned. If no group is specified and the currently
27.2207 + selected newsgroup is invalid, a 412 response MUST be returned.
27.2208 +
27.2209 + Except that the group argument is optional, that a range argument can
27.2210 + be specified, and that a multi-line data block follows the 211
27.2211 + response code, the LISTGROUP command is identical to the GROUP
27.2212 + command. In particular, when successful, the command sets the
27.2213 + current article number to the first article in the group, if any,
27.2214 + even if this is not within the range specified by the second
27.2215 + argument.
27.2216 +
27.2217 + Note that the range argument is a new feature in this specification
27.2218 + and servers that do not support CAPABILITIES (and therefore do not
27.2219 + conform to this specification) are unlikely to support it.
27.2220 +
27.2221 +6.1.2.3. Examples
27.2222 +
27.2223 + Example of LISTGROUP being used to select a group:
27.2224 +
27.2225 + [C] LISTGROUP misc.test
27.2226 + [S] 211 2000 3000234 3002322 misc.test list follows
27.2227 + [S] 3000234
27.2228 + [S] 3000237
27.2229 + [S] 3000238
27.2230 + [S] 3000239
27.2231 + [S] 3002322
27.2232 + [S] .
27.2233 +
27.2234 +
27.2235 +
27.2236 +
27.2237 +
27.2238 +
27.2239 +
27.2240 +Feather Standards Track [Page 40]
27.2241 +
27.2242 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2243 +
27.2244 +
27.2245 + Example of LISTGROUP on an empty group:
27.2246 +
27.2247 + [C] LISTGROUP example.empty.newsgroup
27.2248 + [S] 211 0 0 0 example.empty.newsgroup list follows
27.2249 + [S] .
27.2250 +
27.2251 + Example of LISTGROUP on a valid, currently selected newsgroup:
27.2252 +
27.2253 + [C] GROUP misc.test
27.2254 + [S] 211 2000 3000234 3002322 misc.test
27.2255 + [C] LISTGROUP
27.2256 + [S] 211 2000 3000234 3002322 misc.test list follows
27.2257 + [S] 3000234
27.2258 + [S] 3000237
27.2259 + [S] 3000238
27.2260 + [S] 3000239
27.2261 + [S] 3002322
27.2262 + [S] .
27.2263 +
27.2264 + Example of LISTGROUP with a range:
27.2265 +
27.2266 + [C] LISTGROUP misc.test 3000238-3000248
27.2267 + [S] 211 2000 3000234 3002322 misc.test list follows
27.2268 + [S] 3000238
27.2269 + [S] 3000239
27.2270 + [S] .
27.2271 +
27.2272 + Example of LISTGROUP with an empty range:
27.2273 +
27.2274 + [C] LISTGROUP misc.test 12345678-
27.2275 + [S] 211 2000 3000234 3002322 misc.test list follows
27.2276 + [S] .
27.2277 +
27.2278 + Example of LISTGROUP with an invalid range:
27.2279 +
27.2280 + [C] LISTGROUP misc.test 9999-111
27.2281 + [S] 211 2000 3000234 3002322 misc.test list follows
27.2282 + [S] .
27.2283 +
27.2284 +
27.2285 +
27.2286 +
27.2287 +
27.2288 +
27.2289 +
27.2290 +
27.2291 +
27.2292 +
27.2293 +
27.2294 +
27.2295 +
27.2296 +Feather Standards Track [Page 41]
27.2297 +
27.2298 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2299 +
27.2300 +
27.2301 +6.1.3. LAST
27.2302 +
27.2303 +6.1.3.1. Usage
27.2304 +
27.2305 + Indicating capability: READER
27.2306 +
27.2307 + Syntax
27.2308 + LAST
27.2309 +
27.2310 + Responses
27.2311 + 223 n message-id Article found
27.2312 + 412 No newsgroup selected
27.2313 + 420 Current article number is invalid
27.2314 + 422 No previous article in this group
27.2315 +
27.2316 + Parameters
27.2317 + n Article number
27.2318 + message-id Article message-id
27.2319 +
27.2320 +6.1.3.2. Description
27.2321 +
27.2322 + If the currently selected newsgroup is valid, the current article
27.2323 + number MUST be set to the previous article in that newsgroup (that
27.2324 + is, the highest existing article number less than the current article
27.2325 + number). If successful, a response indicating the new current
27.2326 + article number and the message-id of that article MUST be returned.
27.2327 + No article text is sent in response to this command.
27.2328 +
27.2329 + There MAY be no previous article in the group, although the current
27.2330 + article number is not the reported low water mark. There MUST NOT be
27.2331 + a previous article when the current article number is the reported
27.2332 + low water mark.
27.2333 +
27.2334 + Because articles can be removed and added, the results of multiple
27.2335 + LAST and NEXT commands MAY not be consistent over the life of a
27.2336 + particular NNTP session.
27.2337 +
27.2338 + If the current article number is already the first article of the
27.2339 + newsgroup, a 422 response MUST be returned. If the current article
27.2340 + number is invalid, a 420 response MUST be returned. If the currently
27.2341 + selected newsgroup is invalid, a 412 response MUST be returned. In
27.2342 + all three cases, the currently selected newsgroup and current article
27.2343 + number MUST NOT be altered.
27.2344 +
27.2345 +
27.2346 +
27.2347 +
27.2348 +
27.2349 +
27.2350 +
27.2351 +
27.2352 +Feather Standards Track [Page 42]
27.2353 +
27.2354 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2355 +
27.2356 +
27.2357 +6.1.3.3. Examples
27.2358 +
27.2359 + Example of a successful article retrieval using LAST:
27.2360 +
27.2361 + [C] GROUP misc.test
27.2362 + [S] 211 1234 3000234 3002322 misc.test
27.2363 + [C] NEXT
27.2364 + [S] 223 3000237 <668929@example.org> retrieved
27.2365 + [C] LAST
27.2366 + [S] 223 3000234 <45223423@example.com> retrieved
27.2367 +
27.2368 + Example of an attempt to retrieve an article without having selected
27.2369 + a group (via the GROUP command) first:
27.2370 +
27.2371 + [Assumes currently selected newsgroup is invalid.]
27.2372 + [C] LAST
27.2373 + [S] 412 no newsgroup selected
27.2374 +
27.2375 + Example of an attempt to retrieve an article using the LAST command
27.2376 + when the current article number is that of the first article in the
27.2377 + group:
27.2378 +
27.2379 + [C] GROUP misc.test
27.2380 + [S] 211 1234 3000234 3002322 misc.test
27.2381 + [C] LAST
27.2382 + [S] 422 No previous article to retrieve
27.2383 +
27.2384 + Example of an attempt to retrieve an article using the LAST command
27.2385 + when the currently selected newsgroup is empty:
27.2386 +
27.2387 + [C] GROUP example.empty.newsgroup
27.2388 + [S] 211 0 0 0 example.empty.newsgroup
27.2389 + [C] LAST
27.2390 + [S] 420 No current article selected
27.2391 +
27.2392 +
27.2393 +
27.2394 +
27.2395 +
27.2396 +
27.2397 +
27.2398 +
27.2399 +
27.2400 +
27.2401 +
27.2402 +
27.2403 +
27.2404 +
27.2405 +
27.2406 +
27.2407 +
27.2408 +Feather Standards Track [Page 43]
27.2409 +
27.2410 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2411 +
27.2412 +
27.2413 +6.1.4. NEXT
27.2414 +
27.2415 +6.1.4.1. Usage
27.2416 +
27.2417 + Indicating capability: READER
27.2418 +
27.2419 + Syntax
27.2420 + NEXT
27.2421 +
27.2422 + Responses
27.2423 + 223 n message-id Article found
27.2424 + 412 No newsgroup selected
27.2425 + 420 Current article number is invalid
27.2426 + 421 No next article in this group
27.2427 +
27.2428 + Parameters
27.2429 + n Article number
27.2430 + message-id Article message-id
27.2431 +
27.2432 +6.1.4.2. Description
27.2433 +
27.2434 + If the currently selected newsgroup is valid, the current article
27.2435 + number MUST be set to the next article in that newsgroup (that is,
27.2436 + the lowest existing article number greater than the current article
27.2437 + number). If successful, a response indicating the new current
27.2438 + article number and the message-id of that article MUST be returned.
27.2439 + No article text is sent in response to this command.
27.2440 +
27.2441 + If the current article number is already the last article of the
27.2442 + newsgroup, a 421 response MUST be returned. In all other aspects
27.2443 + (apart, of course, from the lack of 422 response), this command is
27.2444 + identical to the LAST command (Section 6.1.3).
27.2445 +
27.2446 +6.1.4.3. Examples
27.2447 +
27.2448 + Example of a successful article retrieval using NEXT:
27.2449 +
27.2450 + [C] GROUP misc.test
27.2451 + [S] 211 1234 3000234 3002322 misc.test
27.2452 + [C] NEXT
27.2453 + [S] 223 3000237 <668929@example.org> retrieved
27.2454 +
27.2455 +
27.2456 +
27.2457 +
27.2458 +
27.2459 +
27.2460 +
27.2461 +
27.2462 +
27.2463 +
27.2464 +Feather Standards Track [Page 44]
27.2465 +
27.2466 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2467 +
27.2468 +
27.2469 + Example of an attempt to retrieve an article without having selected
27.2470 + a group (via the GROUP command) first:
27.2471 +
27.2472 + [Assumes currently selected newsgroup is invalid.]
27.2473 + [C] NEXT
27.2474 + [S] 412 no newsgroup selected
27.2475 +
27.2476 + Example of an attempt to retrieve an article using the NEXT command
27.2477 + when the current article number is that of the last article in the
27.2478 + group:
27.2479 +
27.2480 + [C] GROUP misc.test
27.2481 + [S] 211 1234 3000234 3002322 misc.test
27.2482 + [C] STAT 3002322
27.2483 + [S] 223 3002322 <411@example.net> retrieved
27.2484 + [C] NEXT
27.2485 + [S] 421 No next article to retrieve
27.2486 +
27.2487 + Example of an attempt to retrieve an article using the NEXT command
27.2488 + when the currently selected newsgroup is empty:
27.2489 +
27.2490 + [C] GROUP example.empty.newsgroup
27.2491 + [S] 211 0 0 0 example.empty.newsgroup
27.2492 + [C] NEXT
27.2493 + [S] 420 No current article selected
27.2494 +
27.2495 +6.2. Retrieval of Articles and Article Sections
27.2496 +
27.2497 + The ARTICLE, BODY, HEAD, and STAT commands are very similar. They
27.2498 + differ only in the parts of the article that are presented to the
27.2499 + client and in the successful response code. The ARTICLE command is
27.2500 + described here in full, while the other three commands are described
27.2501 + in terms of the differences. As specified in Section 3.6, an article
27.2502 + consists of two parts: the article headers and the article body.
27.2503 +
27.2504 + When responding to one of these commands, the server MUST present the
27.2505 + entire article or appropriate part and MUST NOT attempt to alter or
27.2506 + translate it in any way.
27.2507 +
27.2508 +
27.2509 +
27.2510 +
27.2511 +
27.2512 +
27.2513 +
27.2514 +
27.2515 +
27.2516 +
27.2517 +
27.2518 +
27.2519 +
27.2520 +Feather Standards Track [Page 45]
27.2521 +
27.2522 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2523 +
27.2524 +
27.2525 +6.2.1. ARTICLE
27.2526 +
27.2527 +6.2.1.1. Usage
27.2528 +
27.2529 + Indicating capability: READER
27.2530 +
27.2531 + Syntax
27.2532 + ARTICLE message-id
27.2533 + ARTICLE number
27.2534 + ARTICLE
27.2535 +
27.2536 + Responses
27.2537 +
27.2538 + First form (message-id specified)
27.2539 + 220 0|n message-id Article follows (multi-line)
27.2540 + 430 No article with that message-id
27.2541 +
27.2542 + Second form (article number specified)
27.2543 + 220 n message-id Article follows (multi-line)
27.2544 + 412 No newsgroup selected
27.2545 + 423 No article with that number
27.2546 +
27.2547 + Third form (current article number used)
27.2548 + 220 n message-id Article follows (multi-line)
27.2549 + 412 No newsgroup selected
27.2550 + 420 Current article number is invalid
27.2551 +
27.2552 + Parameters
27.2553 + number Requested article number
27.2554 + n Returned article number
27.2555 + message-id Article message-id
27.2556 +
27.2557 +6.2.1.2. Description
27.2558 +
27.2559 + The ARTICLE command selects an article according to the arguments and
27.2560 + presents the entire article (that is, the headers, an empty line, and
27.2561 + the body, in that order) to the client. The command has three forms.
27.2562 +
27.2563 + In the first form, a message-id is specified, and the server presents
27.2564 + the article with that message-id. In this case, the server MUST NOT
27.2565 + alter the currently selected newsgroup or current article number.
27.2566 + This is both to facilitate the presentation of articles that may be
27.2567 + referenced within another article being read, and because of the
27.2568 + semantic difficulties of determining the proper sequence and
27.2569 + membership of an article that may have been cross-posted to more than
27.2570 + one newsgroup.
27.2571 +
27.2572 +
27.2573 +
27.2574 +
27.2575 +
27.2576 +Feather Standards Track [Page 46]
27.2577 +
27.2578 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2579 +
27.2580 +
27.2581 + In the response, the article number MUST be replaced with zero,
27.2582 + unless there is a currently selected newsgroup and the article is
27.2583 + present in that group, in which case the server MAY use the article's
27.2584 + number in that group. (The server is not required to determine
27.2585 + whether the article is in the currently selected newsgroup or, if so,
27.2586 + what article number it has; the client MUST always be prepared for
27.2587 + zero to be specified.) The server MUST NOT provide an article number
27.2588 + unless use of that number in a second ARTICLE command immediately
27.2589 + following this one would return the same article. Even if the server
27.2590 + chooses to return article numbers in these circumstances, it need not
27.2591 + do so consistently; it MAY return zero to any such command (also see
27.2592 + the STAT examples, Section 6.2.4.3).
27.2593 +
27.2594 + In the second form, an article number is specified. If there is an
27.2595 + article with that number in the currently selected newsgroup, the
27.2596 + server MUST set the current article number to that number.
27.2597 +
27.2598 + In the third form, the article indicated by the current article
27.2599 + number in the currently selected newsgroup is used.
27.2600 +
27.2601 + Note that a previously valid article number MAY become invalid if the
27.2602 + article has been removed. A previously invalid article number MAY
27.2603 + become valid if the article has been reinstated, but this article
27.2604 + number MUST be no less than the reported low water mark for that
27.2605 + group.
27.2606 +
27.2607 + The server MUST NOT change the currently selected newsgroup as a
27.2608 + result of this command. The server MUST NOT change the current
27.2609 + article number except when an article number argument was provided
27.2610 + and the article exists; in particular, it MUST NOT change it
27.2611 + following an unsuccessful response.
27.2612 +
27.2613 + Since the message-id is unique for each article, it may be used by a
27.2614 + client to skip duplicate displays of articles that have been posted
27.2615 + more than once, or to more than one newsgroup.
27.2616 +
27.2617 + The article is returned as a multi-line data block following the 220
27.2618 + response code.
27.2619 +
27.2620 + If the argument is a message-id and no such article exists, a 430
27.2621 + response MUST be returned. If the argument is a number or is omitted
27.2622 + and the currently selected newsgroup is invalid, a 412 response MUST
27.2623 + be returned. If the argument is a number and that article does not
27.2624 + exist in the currently selected newsgroup, a 423 response MUST be
27.2625 + returned. If the argument is omitted and the current article number
27.2626 + is invalid, a 420 response MUST be returned.
27.2627 +
27.2628 +
27.2629 +
27.2630 +
27.2631 +
27.2632 +Feather Standards Track [Page 47]
27.2633 +
27.2634 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2635 +
27.2636 +
27.2637 +6.2.1.3. Examples
27.2638 +
27.2639 + Example of a successful retrieval of an article (explicitly not using
27.2640 + an article number):
27.2641 +
27.2642 + [C] GROUP misc.test
27.2643 + [S] 211 1234 3000234 3002322 misc.test
27.2644 + [C] ARTICLE
27.2645 + [S] 220 3000234 <45223423@example.com>
27.2646 + [S] Path: pathost!demo!whitehouse!not-for-mail
27.2647 + [S] From: "Demo User" <nobody@example.net>
27.2648 + [S] Newsgroups: misc.test
27.2649 + [S] Subject: I am just a test article
27.2650 + [S] Date: 6 Oct 1998 04:38:40 -0500
27.2651 + [S] Organization: An Example Net, Uncertain, Texas
27.2652 + [S] Message-ID: <45223423@example.com>
27.2653 + [S]
27.2654 + [S] This is just a test article.
27.2655 + [S] .
27.2656 +
27.2657 + Example of a successful retrieval of an article by message-id:
27.2658 +
27.2659 + [C] ARTICLE <45223423@example.com>
27.2660 + [S] 220 0 <45223423@example.com>
27.2661 + [S] Path: pathost!demo!whitehouse!not-for-mail
27.2662 + [S] From: "Demo User" <nobody@example.net>
27.2663 + [S] Newsgroups: misc.test
27.2664 + [S] Subject: I am just a test article
27.2665 + [S] Date: 6 Oct 1998 04:38:40 -0500
27.2666 + [S] Organization: An Example Net, Uncertain, Texas
27.2667 + [S] Message-ID: <45223423@example.com>
27.2668 + [S]
27.2669 + [S] This is just a test article.
27.2670 + [S] .
27.2671 +
27.2672 + Example of an unsuccessful retrieval of an article by message-id:
27.2673 +
27.2674 + [C] ARTICLE <i.am.not.there@example.com>
27.2675 + [S] 430 No Such Article Found
27.2676 +
27.2677 + Example of an unsuccessful retrieval of an article by number:
27.2678 +
27.2679 + [C] GROUP misc.test
27.2680 + [S] 211 1234 3000234 3002322 news.groups
27.2681 + [C] ARTICLE 300256
27.2682 + [S] 423 No article with that number
27.2683 +
27.2684 +
27.2685 +
27.2686 +
27.2687 +
27.2688 +Feather Standards Track [Page 48]
27.2689 +
27.2690 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2691 +
27.2692 +
27.2693 + Example of an unsuccessful retrieval of an article by number because
27.2694 + no newsgroup was selected first:
27.2695 +
27.2696 + [Assumes currently selected newsgroup is invalid.]
27.2697 + [C] ARTICLE 300256
27.2698 + [S] 412 No newsgroup selected
27.2699 +
27.2700 + Example of an attempt to retrieve an article when the currently
27.2701 + selected newsgroup is empty:
27.2702 +
27.2703 + [C] GROUP example.empty.newsgroup
27.2704 + [S] 211 0 0 0 example.empty.newsgroup
27.2705 + [C] ARTICLE
27.2706 + [S] 420 No current article selected
27.2707 +
27.2708 +6.2.2. HEAD
27.2709 +
27.2710 +6.2.2.1. Usage
27.2711 +
27.2712 + This command is mandatory.
27.2713 +
27.2714 + Syntax
27.2715 + HEAD message-id
27.2716 + HEAD number
27.2717 + HEAD
27.2718 +
27.2719 + Responses
27.2720 +
27.2721 + First form (message-id specified)
27.2722 + 221 0|n message-id Headers follow (multi-line)
27.2723 + 430 No article with that message-id
27.2724 +
27.2725 + Second form (article number specified)
27.2726 + 221 n message-id Headers follow (multi-line)
27.2727 + 412 No newsgroup selected
27.2728 + 423 No article with that number
27.2729 +
27.2730 + Third form (current article number used)
27.2731 + 221 n message-id Headers follow (multi-line)
27.2732 + 412 No newsgroup selected
27.2733 + 420 Current article number is invalid
27.2734 +
27.2735 + Parameters
27.2736 + number Requested article number
27.2737 + n Returned article number
27.2738 + message-id Article message-id
27.2739 +
27.2740 +
27.2741 +
27.2742 +
27.2743 +
27.2744 +Feather Standards Track [Page 49]
27.2745 +
27.2746 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2747 +
27.2748 +
27.2749 +6.2.2.2. Description
27.2750 +
27.2751 + The HEAD command behaves identically to the ARTICLE command except
27.2752 + that, if the article exists, the response code is 221 instead of 220
27.2753 + and only the headers are presented (the empty line separating the
27.2754 + headers and body MUST NOT be included).
27.2755 +
27.2756 +6.2.2.3. Examples
27.2757 +
27.2758 + Example of a successful retrieval of the headers of an article
27.2759 + (explicitly not using an article number):
27.2760 +
27.2761 + [C] GROUP misc.test
27.2762 + [S] 211 1234 3000234 3002322 misc.test
27.2763 + [C] HEAD
27.2764 + [S] 221 3000234 <45223423@example.com>
27.2765 + [S] Path: pathost!demo!whitehouse!not-for-mail
27.2766 + [S] From: "Demo User" <nobody@example.net>
27.2767 + [S] Newsgroups: misc.test
27.2768 + [S] Subject: I am just a test article
27.2769 + [S] Date: 6 Oct 1998 04:38:40 -0500
27.2770 + [S] Organization: An Example Net, Uncertain, Texas
27.2771 + [S] Message-ID: <45223423@example.com>
27.2772 + [S] .
27.2773 +
27.2774 + Example of a successful retrieval of the headers of an article by
27.2775 + message-id:
27.2776 +
27.2777 + [C] HEAD <45223423@example.com>
27.2778 + [S] 221 0 <45223423@example.com>
27.2779 + [S] Path: pathost!demo!whitehouse!not-for-mail
27.2780 + [S] From: "Demo User" <nobody@example.net>
27.2781 + [S] Newsgroups: misc.test
27.2782 + [S] Subject: I am just a test article
27.2783 + [S] Date: 6 Oct 1998 04:38:40 -0500
27.2784 + [S] Organization: An Example Net, Uncertain, Texas
27.2785 + [S] Message-ID: <45223423@example.com>
27.2786 + [S] .
27.2787 +
27.2788 + Example of an unsuccessful retrieval of the headers of an article by
27.2789 + message-id:
27.2790 +
27.2791 + [C] HEAD <i.am.not.there@example.com>
27.2792 + [S] 430 No Such Article Found
27.2793 +
27.2794 +
27.2795 +
27.2796 +
27.2797 +
27.2798 +
27.2799 +
27.2800 +Feather Standards Track [Page 50]
27.2801 +
27.2802 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2803 +
27.2804 +
27.2805 + Example of an unsuccessful retrieval of the headers of an article by
27.2806 + number:
27.2807 +
27.2808 + [C] GROUP misc.test
27.2809 + [S] 211 1234 3000234 3002322 misc.test
27.2810 + [C] HEAD 300256
27.2811 + [S] 423 No article with that number
27.2812 +
27.2813 + Example of an unsuccessful retrieval of the headers of an article by
27.2814 + number because no newsgroup was selected first:
27.2815 +
27.2816 + [Assumes currently selected newsgroup is invalid.]
27.2817 + [C] HEAD 300256
27.2818 + [S] 412 No newsgroup selected
27.2819 +
27.2820 + Example of an attempt to retrieve the headers of an article when the
27.2821 + currently selected newsgroup is empty:
27.2822 +
27.2823 + [C] GROUP example.empty.newsgroup
27.2824 + [S] 211 0 0 0 example.empty.newsgroup
27.2825 + [C] HEAD
27.2826 + [S] 420 No current article selected
27.2827 +
27.2828 +6.2.3. BODY
27.2829 +
27.2830 +6.2.3.1. Usage
27.2831 +
27.2832 + Indicating capability: READER
27.2833 +
27.2834 + Syntax
27.2835 + BODY message-id
27.2836 + BODY number
27.2837 + BODY
27.2838 +
27.2839 + Responses
27.2840 +
27.2841 + First form (message-id specified)
27.2842 + 222 0|n message-id Body follows (multi-line)
27.2843 + 430 No article with that message-id
27.2844 +
27.2845 + Second form (article number specified)
27.2846 + 222 n message-id Body follows (multi-line)
27.2847 + 412 No newsgroup selected
27.2848 + 423 No article with that number
27.2849 +
27.2850 +
27.2851 +
27.2852 +
27.2853 +
27.2854 +
27.2855 +
27.2856 +Feather Standards Track [Page 51]
27.2857 +
27.2858 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2859 +
27.2860 +
27.2861 + Third form (current article number used)
27.2862 + 222 n message-id Body follows (multi-line)
27.2863 + 412 No newsgroup selected
27.2864 + 420 Current article number is invalid
27.2865 +
27.2866 + Parameters
27.2867 + number Requested article number
27.2868 + n Returned article number
27.2869 + message-id Article message-id
27.2870 +
27.2871 +6.2.3.2. Description
27.2872 +
27.2873 + The BODY command behaves identically to the ARTICLE command except
27.2874 + that, if the article exists, the response code is 222 instead of 220
27.2875 + and only the body is presented (the empty line separating the headers
27.2876 + and body MUST NOT be included).
27.2877 +
27.2878 +6.2.3.3. Examples
27.2879 +
27.2880 + Example of a successful retrieval of the body of an article
27.2881 + (explicitly not using an article number):
27.2882 +
27.2883 + [C] GROUP misc.test
27.2884 + [S] 211 1234 3000234 3002322 misc.test
27.2885 + [C] BODY
27.2886 + [S] 222 3000234 <45223423@example.com>
27.2887 + [S] This is just a test article.
27.2888 + [S] .
27.2889 +
27.2890 + Example of a successful retrieval of the body of an article by
27.2891 + message-id:
27.2892 +
27.2893 + [C] BODY <45223423@example.com>
27.2894 + [S] 222 0 <45223423@example.com>
27.2895 + [S] This is just a test article.
27.2896 + [S] .
27.2897 +
27.2898 + Example of an unsuccessful retrieval of the body of an article by
27.2899 + message-id:
27.2900 +
27.2901 + [C] BODY <i.am.not.there@example.com>
27.2902 + [S] 430 No Such Article Found
27.2903 +
27.2904 +
27.2905 +
27.2906 +
27.2907 +
27.2908 +
27.2909 +
27.2910 +
27.2911 +
27.2912 +Feather Standards Track [Page 52]
27.2913 +
27.2914 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2915 +
27.2916 +
27.2917 + Example of an unsuccessful retrieval of the body of an article by
27.2918 + number:
27.2919 +
27.2920 + [C] GROUP misc.test
27.2921 + [S] 211 1234 3000234 3002322 misc.test
27.2922 + [C] BODY 300256
27.2923 + [S] 423 No article with that number
27.2924 +
27.2925 + Example of an unsuccessful retrieval of the body of an article by
27.2926 + number because no newsgroup was selected first:
27.2927 +
27.2928 + [Assumes currently selected newsgroup is invalid.]
27.2929 + [C] BODY 300256
27.2930 + [S] 412 No newsgroup selected
27.2931 +
27.2932 + Example of an attempt to retrieve the body of an article when the
27.2933 + currently selected newsgroup is empty:
27.2934 +
27.2935 + [C] GROUP example.empty.newsgroup
27.2936 + [S] 211 0 0 0 example.empty.newsgroup
27.2937 + [C] BODY
27.2938 + [S] 420 No current article selected
27.2939 +
27.2940 +6.2.4. STAT
27.2941 +
27.2942 +6.2.4.1. Usage
27.2943 +
27.2944 + This command is mandatory.
27.2945 +
27.2946 + Syntax
27.2947 + STAT message-id
27.2948 + STAT number
27.2949 + STAT
27.2950 +
27.2951 + Responses
27.2952 +
27.2953 + First form (message-id specified)
27.2954 + 223 0|n message-id Article exists
27.2955 + 430 No article with that message-id
27.2956 +
27.2957 + Second form (article number specified)
27.2958 + 223 n message-id Article exists
27.2959 + 412 No newsgroup selected
27.2960 + 423 No article with that number
27.2961 +
27.2962 +
27.2963 +
27.2964 +
27.2965 +
27.2966 +
27.2967 +
27.2968 +Feather Standards Track [Page 53]
27.2969 +
27.2970 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.2971 +
27.2972 +
27.2973 + Third form (current article number used)
27.2974 + 223 n message-id Article exists
27.2975 + 412 No newsgroup selected
27.2976 + 420 Current article number is invalid
27.2977 +
27.2978 + Parameters
27.2979 + number Requested article number
27.2980 + n Returned article number
27.2981 + message-id Article message-id
27.2982 +
27.2983 +6.2.4.2. Description
27.2984 +
27.2985 + The STAT command behaves identically to the ARTICLE command except
27.2986 + that, if the article exists, it is NOT presented to the client and
27.2987 + the response code is 223 instead of 220. Note that the response is
27.2988 + NOT multi-line.
27.2989 +
27.2990 + This command allows the client to determine whether an article exists
27.2991 + and, in the second and third forms, what its message-id is, without
27.2992 + having to process an arbitrary amount of text.
27.2993 +
27.2994 +6.2.4.3. Examples
27.2995 +
27.2996 + Example of STAT on an existing article (explicitly not using an
27.2997 + article number):
27.2998 +
27.2999 + [C] GROUP misc.test
27.3000 + [S] 211 1234 3000234 3002322 misc.test
27.3001 + [C] STAT
27.3002 + [S] 223 3000234 <45223423@example.com>
27.3003 +
27.3004 + Example of STAT on an existing article by message-id:
27.3005 +
27.3006 + [C] STAT <45223423@example.com>
27.3007 + [S] 223 0 <45223423@example.com>
27.3008 +
27.3009 + Example of STAT on an article not on the server by message-id:
27.3010 +
27.3011 + [C] STAT <i.am.not.there@example.com>
27.3012 + [S] 430 No Such Article Found
27.3013 +
27.3014 + Example of STAT on an article not in the server by number:
27.3015 +
27.3016 + [C] GROUP misc.test
27.3017 + [S] 211 1234 3000234 3002322 misc.test
27.3018 + [C] STAT 300256
27.3019 + [S] 423 No article with that number
27.3020 +
27.3021 +
27.3022 +
27.3023 +
27.3024 +Feather Standards Track [Page 54]
27.3025 +
27.3026 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3027 +
27.3028 +
27.3029 + Example of STAT on an article by number when no newsgroup was
27.3030 + selected first:
27.3031 +
27.3032 + [Assumes currently selected newsgroup is invalid.]
27.3033 + [C] STAT 300256
27.3034 + [S] 412 No newsgroup selected
27.3035 +
27.3036 + Example of STAT on an article when the currently selected newsgroup
27.3037 + is empty:
27.3038 +
27.3039 + [C] GROUP example.empty.newsgroup
27.3040 + [S] 211 0 0 0 example.empty.newsgroup
27.3041 + [C] STAT
27.3042 + [S] 420 No current article selected
27.3043 +
27.3044 + Example of STAT by message-id on a server that sometimes reports the
27.3045 + actual article number:
27.3046 +
27.3047 + [C] GROUP misc.test
27.3048 + [S] 211 1234 3000234 3002322 misc.test
27.3049 + [C] STAT
27.3050 + [S] 223 3000234 <45223423@example.com>
27.3051 + [C] STAT <45223423@example.com>
27.3052 + [S] 223 0 <45223423@example.com>
27.3053 + [C] STAT <45223423@example.com>
27.3054 + [S] 223 3000234 <45223423@example.com>
27.3055 + [C] GROUP example.empty.newsgroup
27.3056 + [S] 211 0 0 0 example.empty.newsgroup
27.3057 + [C] STAT <45223423@example.com>
27.3058 + [S] 223 0 <45223423@example.com>
27.3059 + [C] GROUP alt.crossposts
27.3060 + [S] 211 9999 111111 222222 alt.crossposts
27.3061 + [C] STAT <45223423@example.com>
27.3062 + [S] 223 123456 <45223423@example.com>
27.3063 + [C] STAT
27.3064 + [S] 223 111111 <23894720@example.com>
27.3065 +
27.3066 + The first STAT command establishes the identity of an article in the
27.3067 + group. The second and third show that the server may, but need not,
27.3068 + give the article number when the message-id is specified. The fourth
27.3069 + STAT command shows that zero must be specified if the article isn't
27.3070 + in the currently selected newsgroup. The fifth shows that the
27.3071 + number, if provided, must be that relating to the currently selected
27.3072 + newsgroup. The last one shows that the current article number is
27.3073 + still not changed by the use of STAT with a message-id even if it
27.3074 + returns an article number.
27.3075 +
27.3076 +
27.3077 +
27.3078 +
27.3079 +
27.3080 +Feather Standards Track [Page 55]
27.3081 +
27.3082 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3083 +
27.3084 +
27.3085 +6.3. Article Posting
27.3086 +
27.3087 + Article posting is done in one of two ways: individual article
27.3088 + posting from news-reading clients using POST, and article transfer
27.3089 + from other news servers using IHAVE.
27.3090 +
27.3091 +6.3.1. POST
27.3092 +
27.3093 +6.3.1.1. Usage
27.3094 +
27.3095 + Indicating capability: POST
27.3096 +
27.3097 + This command MUST NOT be pipelined.
27.3098 +
27.3099 + Syntax
27.3100 + POST
27.3101 +
27.3102 + Responses
27.3103 +
27.3104 + Initial responses
27.3105 + 340 Send article to be posted
27.3106 + 440 Posting not permitted
27.3107 +
27.3108 + Subsequent responses
27.3109 + 240 Article received OK
27.3110 + 441 Posting failed
27.3111 +
27.3112 +6.3.1.2. Description
27.3113 +
27.3114 + If posting is allowed, a 340 response MUST be returned to indicate
27.3115 + that the article to be posted should be sent. If posting is
27.3116 + prohibited for some installation-dependent reason, a 440 response
27.3117 + MUST be returned.
27.3118 +
27.3119 + If posting is permitted, the article MUST be in the format specified
27.3120 + in Section 3.6 and MUST be sent by the client to the server as a
27.3121 + multi-line data block (see Section 3.1.1). Thus a single dot (".")
27.3122 + on a line indicates the end of the text, and lines starting with a
27.3123 + dot in the original text have that dot doubled during transmission.
27.3124 +
27.3125 + Following the presentation of the termination sequence by the client,
27.3126 + the server MUST return a response indicating success or failure of
27.3127 + the article transfer. Note that response codes 340 and 440 are used
27.3128 + in direct response to the POST command while 240 and 441 are returned
27.3129 + after the article is sent.
27.3130 +
27.3131 +
27.3132 +
27.3133 +
27.3134 +
27.3135 +
27.3136 +Feather Standards Track [Page 56]
27.3137 +
27.3138 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3139 +
27.3140 +
27.3141 + A response of 240 SHOULD indicate that, barring unforeseen server
27.3142 + errors, the posted article will be made available on the server
27.3143 + and/or transferred to other servers, as appropriate, possibly
27.3144 + following further processing. In other words, articles not wanted by
27.3145 + the server SHOULD be rejected with a 441 response, rather than being
27.3146 + accepted and then discarded silently. However, the client SHOULD NOT
27.3147 + assume that the article has been successfully transferred unless it
27.3148 + receives an affirmative response from the server and SHOULD NOT
27.3149 + assume that it is being made available to other clients without
27.3150 + explicitly checking (for example, using the STAT command).
27.3151 +
27.3152 + If the session is interrupted before the response is received, it is
27.3153 + possible that an affirmative response was sent but has been lost.
27.3154 + Therefore, in any subsequent session, the client SHOULD either check
27.3155 + whether the article was successfully posted before resending or
27.3156 + ensure that the server will allocate the same message-id to the new
27.3157 + attempt (see Appendix A.2). The latter approach is preferred since
27.3158 + the article might not have been made available for reading yet (for
27.3159 + example, it may have to go through a moderation process).
27.3160 +
27.3161 +6.3.1.3. Examples
27.3162 +
27.3163 + Example of a successful posting:
27.3164 +
27.3165 + [C] POST
27.3166 + [S] 340 Input article; end with <CR-LF>.<CR-LF>
27.3167 + [C] From: "Demo User" <nobody@example.net>
27.3168 + [C] Newsgroups: misc.test
27.3169 + [C] Subject: I am just a test article
27.3170 + [C] Organization: An Example Net
27.3171 + [C]
27.3172 + [C] This is just a test article.
27.3173 + [C] .
27.3174 + [S] 240 Article received OK
27.3175 +
27.3176 + Example of an unsuccessful posting:
27.3177 +
27.3178 + [C] POST
27.3179 + [S] 340 Input article; end with <CR-LF>.<CR-LF>
27.3180 + [C] From: "Demo User" <nobody@example.net>
27.3181 + [C] Newsgroups: misc.test
27.3182 + [C] Subject: I am just a test article
27.3183 + [C] Organization: An Example Net
27.3184 + [C]
27.3185 + [C] This is just a test article.
27.3186 + [C] .
27.3187 + [S] 441 Posting failed
27.3188 +
27.3189 +
27.3190 +
27.3191 +
27.3192 +Feather Standards Track [Page 57]
27.3193 +
27.3194 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3195 +
27.3196 +
27.3197 + Example of an attempt to post when posting is not allowed:
27.3198 +
27.3199 + [Initial connection set-up completed.]
27.3200 + [S] 201 NNTP Service Ready, posting prohibited
27.3201 + [C] POST
27.3202 + [S] 440 Posting not permitted
27.3203 +
27.3204 +6.3.2. IHAVE
27.3205 +
27.3206 +6.3.2.1. Usage
27.3207 +
27.3208 + Indicating capability: IHAVE
27.3209 +
27.3210 + This command MUST NOT be pipelined.
27.3211 +
27.3212 + Syntax
27.3213 + IHAVE message-id
27.3214 +
27.3215 + Responses
27.3216 +
27.3217 + Initial responses
27.3218 + 335 Send article to be transferred
27.3219 + 435 Article not wanted
27.3220 + 436 Transfer not possible; try again later
27.3221 +
27.3222 + Subsequent responses
27.3223 + 235 Article transferred OK
27.3224 + 436 Transfer failed; try again later
27.3225 + 437 Transfer rejected; do not retry
27.3226 +
27.3227 + Parameters
27.3228 + message-id Article message-id
27.3229 +
27.3230 +6.3.2.2. Description
27.3231 +
27.3232 + The IHAVE command informs the server that the client has an article
27.3233 + with the specified message-id. If the server desires a copy of that
27.3234 + article, a 335 response MUST be returned, instructing the client to
27.3235 + send the entire article. If the server does not want the article
27.3236 + (if, for example, the server already has a copy of it), a 435
27.3237 + response MUST be returned, indicating that the article is not wanted.
27.3238 + Finally, if the article isn't wanted immediately but the client
27.3239 + should retry later if possible (if, for example, another client is in
27.3240 + the process of sending the same article to the server), a 436
27.3241 + response MUST be returned.
27.3242 +
27.3243 +
27.3244 +
27.3245 +
27.3246 +
27.3247 +
27.3248 +Feather Standards Track [Page 58]
27.3249 +
27.3250 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3251 +
27.3252 +
27.3253 + If transmission of the article is requested, the client MUST send the
27.3254 + entire article, including headers and body, to the server as a
27.3255 + multi-line data block (see Section 3.1.1). Thus, a single dot (".")
27.3256 + on a line indicates the end of the text, and lines starting with a
27.3257 + dot in the original text have that dot doubled during transmission.
27.3258 + The server MUST return a 235 response, indicating that the article
27.3259 + was successfully transferred; a 436 response, indicating that the
27.3260 + transfer failed but should be tried again later; or a 437 response,
27.3261 + indicating that the article was rejected.
27.3262 +
27.3263 + This function differs from the POST command in that it is intended
27.3264 + for use in transferring already-posted articles between hosts. It
27.3265 + SHOULD NOT be used when the client is a personal news-reading
27.3266 + program, since use of this command indicates that the article has
27.3267 + already been posted at another site and is simply being forwarded
27.3268 + from another host. However, despite this, the server MAY elect not
27.3269 + to post or forward the article if, after further examination of the
27.3270 + article, it deems it inappropriate to do so. Reasons for such
27.3271 + subsequent rejection of an article may include problems such as
27.3272 + inappropriate newsgroups or distributions, disc space limitations,
27.3273 + article lengths, garbled headers, and the like. These are typically
27.3274 + restrictions enforced by the server host's news software and not
27.3275 + necessarily by the NNTP server itself.
27.3276 +
27.3277 + The client SHOULD NOT assume that the article has been successfully
27.3278 + transferred unless it receives an affirmative response from the
27.3279 + server. A lack of response (such as a dropped network connection or
27.3280 + a network timeout) SHOULD be treated the same as a 436 response.
27.3281 +
27.3282 + Because some news server software may not immediately be able to
27.3283 + determine whether an article is suitable for posting or forwarding,
27.3284 + an NNTP server MAY acknowledge the successful transfer of the article
27.3285 + (with a 235 response) but later silently discard it.
27.3286 +
27.3287 +
27.3288 +
27.3289 +
27.3290 +
27.3291 +
27.3292 +
27.3293 +
27.3294 +
27.3295 +
27.3296 +
27.3297 +
27.3298 +
27.3299 +
27.3300 +
27.3301 +
27.3302 +
27.3303 +
27.3304 +Feather Standards Track [Page 59]
27.3305 +
27.3306 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3307 +
27.3308 +
27.3309 +6.3.2.3. Examples
27.3310 +
27.3311 + Example of successfully sending an article to another site:
27.3312 +
27.3313 + [C] IHAVE <i.am.an.article.you.will.want@example.com>
27.3314 + [S] 335 Send it; end with <CR-LF>.<CR-LF>
27.3315 + [C] Path: pathost!demo!somewhere!not-for-mail
27.3316 + [C] From: "Demo User" <nobody@example.com>
27.3317 + [C] Newsgroups: misc.test
27.3318 + [C] Subject: I am just a test article
27.3319 + [C] Date: 6 Oct 1998 04:38:40 -0500
27.3320 + [C] Organization: An Example Com, San Jose, CA
27.3321 + [C] Message-ID: <i.am.an.article.you.will.want@example.com>
27.3322 + [C]
27.3323 + [C] This is just a test article.
27.3324 + [C] .
27.3325 + [S] 235 Article transferred OK
27.3326 +
27.3327 + Example of sending an article to another site that rejects it. Note
27.3328 + that the message-id in the IHAVE command is not the same as the one
27.3329 + in the article headers; while this is bad practice and SHOULD NOT be
27.3330 + done, it is not forbidden.
27.3331 +
27.3332 + [C] IHAVE <i.am.an.article.you.will.want@example.com>
27.3333 + [S] 335 Send it; end with <CR-LF>.<CR-LF>
27.3334 + [C] Path: pathost!demo!somewhere!not-for-mail
27.3335 + [C] From: "Demo User" <nobody@example.com>
27.3336 + [C] Newsgroups: misc.test
27.3337 + [C] Subject: I am just a test article
27.3338 + [C] Date: 6 Oct 1998 04:38:40 -0500
27.3339 + [C] Organization: An Example Com, San Jose, CA
27.3340 + [C] Message-ID: <i.am.an.article.you.have@example.com>
27.3341 + [C]
27.3342 + [C] This is just a test article.
27.3343 + [C] .
27.3344 + [S] 437 Article rejected; don't send again
27.3345 +
27.3346 +
27.3347 +
27.3348 +
27.3349 +
27.3350 +
27.3351 +
27.3352 +
27.3353 +
27.3354 +
27.3355 +
27.3356 +
27.3357 +
27.3358 +
27.3359 +
27.3360 +Feather Standards Track [Page 60]
27.3361 +
27.3362 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3363 +
27.3364 +
27.3365 + Example of sending an article to another site where the transfer
27.3366 + fails:
27.3367 +
27.3368 + [C] IHAVE <i.am.an.article.you.will.want@example.com>
27.3369 + [S] 335 Send it; end with <CR-LF>.<CR-LF>
27.3370 + [C] Path: pathost!demo!somewhere!not-for-mail
27.3371 + [C] From: "Demo User" <nobody@example.com>
27.3372 + [C] Newsgroups: misc.test
27.3373 + [C] Subject: I am just a test article
27.3374 + [C] Date: 6 Oct 1998 04:38:40 -0500
27.3375 + [C] Organization: An Example Com, San Jose, CA
27.3376 + [C] Message-ID: <i.am.an.article.you.will.want@example.com>
27.3377 + [C]
27.3378 + [C] This is just a test article.
27.3379 + [C] .
27.3380 + [S] 436 Transfer failed
27.3381 +
27.3382 + Example of sending an article to a site that already has it:
27.3383 +
27.3384 + [C] IHAVE <i.am.an.article.you.have@example.com>
27.3385 + [S] 435 Duplicate
27.3386 +
27.3387 + Example of sending an article to a site that requests that the
27.3388 + article be tried again later:
27.3389 +
27.3390 + [C] IHAVE <i.am.an.article.you.defer@example.com>
27.3391 + [S] 436 Retry later
27.3392 +
27.3393 +7. Information Commands
27.3394 +
27.3395 + This section lists other commands that may be used at any time
27.3396 + between the beginning of a session and its termination. Using these
27.3397 + commands does not alter any state information, but the response
27.3398 + generated from their use may provide useful information to clients.
27.3399 +
27.3400 +7.1. DATE
27.3401 +
27.3402 +7.1.1. Usage
27.3403 +
27.3404 + Indicating capability: READER
27.3405 +
27.3406 + Syntax
27.3407 + DATE
27.3408 +
27.3409 + Responses
27.3410 + 111 yyyymmddhhmmss Server date and time
27.3411 +
27.3412 +
27.3413 +
27.3414 +
27.3415 +
27.3416 +Feather Standards Track [Page 61]
27.3417 +
27.3418 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3419 +
27.3420 +
27.3421 + Parameters
27.3422 + yyyymmddhhmmss Current UTC date and time on server
27.3423 +
27.3424 +7.1.2. Description
27.3425 +
27.3426 + This command exists to help clients find out the current Coordinated
27.3427 + Universal Time [TF.686-1] from the server's perspective. This
27.3428 + command SHOULD NOT be used as a substitute for NTP [RFC1305] but to
27.3429 + provide information that might be useful when using the NEWNEWS
27.3430 + command (see Section 7.4).
27.3431 +
27.3432 + The DATE command MUST return a timestamp from the same clock as is
27.3433 + used for determining article arrival and group creation times (see
27.3434 + Section 6). This clock SHOULD be monotonic, and adjustments SHOULD
27.3435 + be made by running it fast or slow compared to "real" time rather
27.3436 + than by making sudden jumps. A system providing NNTP service SHOULD
27.3437 + keep the system clock as accurate as possible, either with NTP or by
27.3438 + some other method.
27.3439 +
27.3440 + The server MUST return a 111 response specifying the date and time on
27.3441 + the server in the form yyyymmddhhmmss. This date and time is in
27.3442 + Coordinated Universal Time.
27.3443 +
27.3444 +7.1.3. Examples
27.3445 +
27.3446 + [C] DATE
27.3447 + [S] 111 19990623135624
27.3448 +
27.3449 +7.2. HELP
27.3450 +
27.3451 +7.2.1. Usage
27.3452 +
27.3453 + This command is mandatory.
27.3454 +
27.3455 + Syntax
27.3456 + HELP
27.3457 +
27.3458 + Responses
27.3459 + 100 Help text follows (multi-line)
27.3460 +
27.3461 +7.2.2. Description
27.3462 +
27.3463 + This command provides a short summary of the commands that are
27.3464 + understood by this implementation of the server. The help text will
27.3465 + be presented as a multi-line data block following the 100 response
27.3466 + code.
27.3467 +
27.3468 +
27.3469 +
27.3470 +
27.3471 +
27.3472 +Feather Standards Track [Page 62]
27.3473 +
27.3474 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3475 +
27.3476 +
27.3477 + This text is not guaranteed to be in any particular format (but must
27.3478 + be UTF-8) and MUST NOT be used by clients as a replacement for the
27.3479 + CAPABILITIES command described in Section 5.2.
27.3480 +
27.3481 +7.2.3. Examples
27.3482 +
27.3483 + [C] HELP
27.3484 + [S] 100 Help text follows
27.3485 + [S] This is some help text. There is no specific
27.3486 + [S] formatting requirement for this test, though
27.3487 + [S] it is customary for it to list the valid commands
27.3488 + [S] and give a brief definition of what they do.
27.3489 + [S] .
27.3490 +
27.3491 +7.3. NEWGROUPS
27.3492 +
27.3493 +7.3.1. Usage
27.3494 +
27.3495 + Indicating capability: READER
27.3496 +
27.3497 + Syntax
27.3498 + NEWGROUPS date time [GMT]
27.3499 +
27.3500 + Responses
27.3501 + 231 List of new newsgroups follows (multi-line)
27.3502 +
27.3503 + Parameters
27.3504 + date Date in yymmdd or yyyymmdd format
27.3505 + time Time in hhmmss format
27.3506 +
27.3507 +7.3.2. Description
27.3508 +
27.3509 + This command returns a list of newsgroups created on the server since
27.3510 + the specified date and time. The results are in the same format as
27.3511 + the LIST ACTIVE command (see Section 7.6.3). However, they MAY
27.3512 + include groups not available on the server (and so not returned by
27.3513 + LIST ACTIVE) and MAY omit groups for which the creation date is not
27.3514 + available.
27.3515 +
27.3516 + The date is specified as 6 or 8 digits in the format [xx]yymmdd,
27.3517 + where xx is the first two digits of the year (19-99), yy is the last
27.3518 + two digits of the year (00-99), mm is the month (01-12), and dd is
27.3519 + the day of the month (01-31). Clients SHOULD specify all four digits
27.3520 + of the year. If the first two digits of the year are not specified
27.3521 + (this is supported only for backward compatibility), the year is to
27.3522 + be taken from the current century if yy is smaller than or equal to
27.3523 + the current year, and the previous century otherwise.
27.3524 +
27.3525 +
27.3526 +
27.3527 +
27.3528 +Feather Standards Track [Page 63]
27.3529 +
27.3530 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3531 +
27.3532 +
27.3533 + The time is specified as 6 digits in the format hhmmss, where hh is
27.3534 + the hours in the 24-hour clock (00-23), mm is the minutes (00-59),
27.3535 + and ss is the seconds (00-60, to allow for leap seconds). The token
27.3536 + "GMT" specifies that the date and time are given in Coordinated
27.3537 + Universal Time [TF.686-1]; if it is omitted, then the date and time
27.3538 + are specified in the server's local timezone. Note that there is no
27.3539 + way of using the protocol specified in this document to establish the
27.3540 + server's local timezone.
27.3541 +
27.3542 + Note that an empty list is a possible valid response and indicates
27.3543 + that there are no new newsgroups since that date-time.
27.3544 +
27.3545 + Clients SHOULD make all queries using Coordinated Universal Time
27.3546 + (i.e., by including the "GMT" argument) when possible.
27.3547 +
27.3548 +7.3.3. Examples
27.3549 +
27.3550 + Example where there are new groups:
27.3551 +
27.3552 + [C] NEWGROUPS 19990624 000000 GMT
27.3553 + [S] 231 list of new newsgroups follows
27.3554 + [S] alt.rfc-writers.recovery 4 1 y
27.3555 + [S] tx.natives.recovery 89 56 y
27.3556 + [S] .
27.3557 +
27.3558 + Example where there are no new groups:
27.3559 +
27.3560 + [C] NEWGROUPS 19990624 000000 GMT
27.3561 + [S] 231 list of new newsgroups follows
27.3562 + [S] .
27.3563 +
27.3564 +7.4. NEWNEWS
27.3565 +
27.3566 +7.4.1. Usage
27.3567 +
27.3568 + Indicating capability: NEWNEWS
27.3569 +
27.3570 + Syntax
27.3571 + NEWNEWS wildmat date time [GMT]
27.3572 +
27.3573 + Responses
27.3574 + 230 List of new articles follows (multi-line)
27.3575 +
27.3576 + Parameters
27.3577 + wildmat Newsgroups of interest
27.3578 + date Date in yymmdd or yyyymmdd format
27.3579 + time Time in hhmmss format
27.3580 +
27.3581 +
27.3582 +
27.3583 +
27.3584 +Feather Standards Track [Page 64]
27.3585 +
27.3586 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3587 +
27.3588 +
27.3589 +7.4.2. Description
27.3590 +
27.3591 + This command returns a list of message-ids of articles posted or
27.3592 + received on the server, in the newsgroups whose names match the
27.3593 + wildmat, since the specified date and time. One message-id is sent
27.3594 + on each line; the order of the response has no specific significance
27.3595 + and may vary from response to response in the same session. A
27.3596 + message-id MAY appear more than once; if it does, it has the same
27.3597 + meaning as if it appeared only once.
27.3598 +
27.3599 + Date and time are in the same format as the NEWGROUPS command (see
27.3600 + Section 7.3).
27.3601 +
27.3602 + Note that an empty list is a possible valid response and indicates
27.3603 + that there is currently no new news in the relevant groups.
27.3604 +
27.3605 + Clients SHOULD make all queries in Coordinated Universal Time (i.e.,
27.3606 + by using the "GMT" argument) when possible.
27.3607 +
27.3608 +7.4.3. Examples
27.3609 +
27.3610 + Example where there are new articles:
27.3611 +
27.3612 + [C] NEWNEWS news.*,sci.* 19990624 000000 GMT
27.3613 + [S] 230 list of new articles by message-id follows
27.3614 + [S] <i.am.a.new.article@example.com>
27.3615 + [S] <i.am.another.new.article@example.com>
27.3616 + [S] .
27.3617 +
27.3618 + Example where there are no new articles:
27.3619 +
27.3620 + [C] NEWNEWS alt.* 19990624 000000 GMT
27.3621 + [S] 230 list of new articles by message-id follows
27.3622 + [S] .
27.3623 +
27.3624 +7.5. Time
27.3625 +
27.3626 + As described in Section 6, each article has an arrival timestamp.
27.3627 + Each newsgroup also has a creation timestamp. These timestamps are
27.3628 + used by the NEWNEWS and NEWGROUP commands to construct their
27.3629 + responses.
27.3630 +
27.3631 + Clients can ensure that they do not have gaps in lists of articles or
27.3632 + groups by using the DATE command in the following manner:
27.3633 +
27.3634 + First session:
27.3635 + Issue DATE command and record result.
27.3636 + Issue NEWNEWS command using a previously chosen timestamp.
27.3637 +
27.3638 +
27.3639 +
27.3640 +Feather Standards Track [Page 65]
27.3641 +
27.3642 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3643 +
27.3644 +
27.3645 + Subsequent sessions:
27.3646 + Issue DATE command and hold result in temporary storage.
27.3647 + Issue NEWNEWS command using timestamp saved from previous session.
27.3648 + Overwrite saved timestamp with that currently in temporary
27.3649 + storage.
27.3650 +
27.3651 + In order to allow for minor errors, clients MAY want to adjust the
27.3652 + timestamp back by two or three minutes before using it in NEWNEWS.
27.3653 +
27.3654 +7.5.1. Examples
27.3655 +
27.3656 + First session:
27.3657 +
27.3658 + [C] DATE
27.3659 + [S] 111 20010203112233
27.3660 + [C] NEWNEWS local.chat 20001231 235959 GMT
27.3661 + [S] 230 list follows
27.3662 + [S] <article.1@local.service>
27.3663 + [S] <article.2@local.service>
27.3664 + [S] <article.3@local.service>
27.3665 + [S] .
27.3666 +
27.3667 + Second session (the client has subtracted 3 minutes from the
27.3668 + timestamp returned previously):
27.3669 +
27.3670 + [C] DATE
27.3671 + [S] 111 20010204003344
27.3672 + [C] NEWNEWS local.chat 20010203 111933 GMT
27.3673 + [S] 230 list follows
27.3674 + [S] <article.3@local.service>
27.3675 + [S] <article.4@local.service>
27.3676 + [S] <article.5@local.service>
27.3677 + [S] .
27.3678 +
27.3679 + Note how <article.3@local.service> arrived in the 3 minute gap and so
27.3680 + is listed in both responses.
27.3681 +
27.3682 +7.6. The LIST Commands
27.3683 +
27.3684 + The LIST family of commands all return information that is multi-line
27.3685 + and that can, in general, be expected not to change during the
27.3686 + session. Often the information is related to newsgroups, in which
27.3687 + case the response has one line per newsgroup and a wildmat MAY be
27.3688 + provided to restrict the groups for which information is returned.
27.3689 +
27.3690 + The set of available keywords (including those provided by
27.3691 + extensions) is given in the capability list with capability label
27.3692 + LIST.
27.3693 +
27.3694 +
27.3695 +
27.3696 +Feather Standards Track [Page 66]
27.3697 +
27.3698 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3699 +
27.3700 +
27.3701 +7.6.1. LIST
27.3702 +
27.3703 +7.6.1.1. Usage
27.3704 +
27.3705 + Indicating capability: LIST
27.3706 +
27.3707 + Syntax
27.3708 + LIST [keyword [wildmat|argument]]
27.3709 +
27.3710 + Responses
27.3711 + 215 Information follows (multi-line)
27.3712 +
27.3713 + Parameters
27.3714 + keyword Information requested [1]
27.3715 + argument Specific to keyword
27.3716 + wildmat Groups of interest
27.3717 +
27.3718 + [1] If no keyword is provided, it defaults to ACTIVE.
27.3719 +
27.3720 +7.6.1.2. Description
27.3721 +
27.3722 + The LIST command allows the server to provide blocks of information
27.3723 + to the client. This information may be global or may be related to
27.3724 + newsgroups; in the latter case, the information may be returned
27.3725 + either for all groups or only for those matching a wildmat. Each
27.3726 + block of information is represented by a different keyword. The
27.3727 + command returns the specific information identified by the keyword.
27.3728 +
27.3729 + If the information is available, it is returned as a multi-line data
27.3730 + block following the 215 response code. The format of the information
27.3731 + depends on the keyword. The information MAY be affected by the
27.3732 + additional argument, but the format MUST NOT be.
27.3733 +
27.3734 + If the information is based on newsgroups and the optional wildmat
27.3735 + argument is specified, the response is limited to only the groups (if
27.3736 + any) whose names match the wildmat and for which the information is
27.3737 + available.
27.3738 +
27.3739 + Note that an empty list is a possible valid response; for a
27.3740 + newsgroup-based keyword, it indicates that there are no groups
27.3741 + meeting the above criteria.
27.3742 +
27.3743 + If the keyword is not recognised, or if an argument is specified and
27.3744 + the keyword does not expect one, a 501 response code MUST BE
27.3745 + returned. If the keyword is recognised but the server does not
27.3746 + maintain the information, a 503 response code MUST BE returned.
27.3747 +
27.3748 +
27.3749 +
27.3750 +
27.3751 +
27.3752 +Feather Standards Track [Page 67]
27.3753 +
27.3754 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3755 +
27.3756 +
27.3757 + The LIST command MUST NOT change the visible state of the server in
27.3758 + any way; that is, the behaviour of subsequent commands MUST NOT be
27.3759 + affected by whether the LIST command was issued. For example, it
27.3760 + MUST NOT make groups available that otherwise would not have been.
27.3761 +
27.3762 +7.6.1.3. Examples
27.3763 +
27.3764 + Example of LIST with the ACTIVE keyword:
27.3765 +
27.3766 + [C] LIST ACTIVE
27.3767 + [S] 215 list of newsgroups follows
27.3768 + [S] misc.test 3002322 3000234 y
27.3769 + [S] comp.risks 442001 441099 m
27.3770 + [S] alt.rfc-writers.recovery 4 1 y
27.3771 + [S] tx.natives.recovery 89 56 y
27.3772 + [S] tx.natives.recovery.d 11 9 n
27.3773 + [S] .
27.3774 +
27.3775 + Example of LIST with no keyword:
27.3776 +
27.3777 + [C] LIST
27.3778 + [S] 215 list of newsgroups follows
27.3779 + [S] misc.test 3002322 3000234 y
27.3780 + [S] comp.risks 442001 441099 m
27.3781 + [S] alt.rfc-writers.recovery 4 1 y
27.3782 + [S] tx.natives.recovery 89 56 y
27.3783 + [S] tx.natives.recovery.d 11 9 n
27.3784 + [S] .
27.3785 +
27.3786 + The output is identical to that of the previous example.
27.3787 +
27.3788 + Example of LIST on a newsgroup-based keyword with and without
27.3789 + wildmat:
27.3790 +
27.3791 + [C] LIST ACTIVE.TIMES
27.3792 + [S] 215 information follows
27.3793 + [S] misc.test 930445408 <creatme@isc.org>
27.3794 + [S] alt.rfc-writers.recovery 930562309 <m@example.com>
27.3795 + [S] tx.natives.recovery 930678923 <sob@academ.com>
27.3796 + [S] .
27.3797 + [C] LIST ACTIVE.TIMES tx.*
27.3798 + [S] 215 information follows
27.3799 + [S] tx.natives.recovery 930678923 <sob@academ.com>
27.3800 + [S] .
27.3801 +
27.3802 +
27.3803 +
27.3804 +
27.3805 +
27.3806 +
27.3807 +
27.3808 +Feather Standards Track [Page 68]
27.3809 +
27.3810 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3811 +
27.3812 +
27.3813 + Example of LIST returning an error where the keyword is recognized
27.3814 + but the software does not maintain this information:
27.3815 +
27.3816 + [C] CAPABILITIES
27.3817 + [S] 101 Capability list:
27.3818 + [S] VERSION 2
27.3819 + [S] READER
27.3820 + [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
27.3821 + [S] .
27.3822 + [C] LIST XTRA.DATA
27.3823 + [S] 503 Data item not stored
27.3824 +
27.3825 + Example of LIST where the keyword is not recognised:
27.3826 +
27.3827 + [C] CAPABILITIES
27.3828 + [S] 101 Capability list:
27.3829 + [S] VERSION 2
27.3830 + [S] READER
27.3831 + [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
27.3832 + [S] .
27.3833 + [C] LIST DISTRIB.PATS
27.3834 + [S] 501 Syntax Error
27.3835 +
27.3836 +7.6.2. Standard LIST Keywords
27.3837 +
27.3838 + This specification defines the following LIST keywords:
27.3839 +
27.3840 + +--------------+---------------+------------------------------------+
27.3841 + | Keyword | Definition | Status |
27.3842 + +--------------+---------------+------------------------------------+
27.3843 + | ACTIVE | Section 7.6.3 | Mandatory if the READER capability |
27.3844 + | | | is advertised |
27.3845 + | | | |
27.3846 + | ACTIVE.TIMES | Section 7.6.4 | Optional |
27.3847 + | | | |
27.3848 + | DISTRIB.PATS | Section 7.6.5 | Optional |
27.3849 + | | | |
27.3850 + | HEADERS | Section 8.6 | Mandatory if the HDR capability is |
27.3851 + | | | advertised |
27.3852 + | | | |
27.3853 + | NEWSGROUPS | Section 7.6.6 | Mandatory if the READER capability |
27.3854 + | | | is advertised |
27.3855 + | | | |
27.3856 + | OVERVIEW.FMT | Section 8.4 | Mandatory if the OVER capability |
27.3857 + | | | is advertised |
27.3858 + +--------------+---------------+------------------------------------+
27.3859 +
27.3860 +
27.3861 +
27.3862 +
27.3863 +
27.3864 +Feather Standards Track [Page 69]
27.3865 +
27.3866 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3867 +
27.3868 +
27.3869 + Where one of these LIST keywords is supported by a server, it MUST
27.3870 + have the meaning given in the relevant sub-section.
27.3871 +
27.3872 +7.6.3. LIST ACTIVE
27.3873 +
27.3874 + This keyword MUST be supported by servers advertising the READER
27.3875 + capability.
27.3876 +
27.3877 + LIST ACTIVE returns a list of valid newsgroups and associated
27.3878 + information. If no wildmat is specified, the server MUST include
27.3879 + every group that the client is permitted to select with the GROUP
27.3880 + command (Section 6.1.1). Each line of this list consists of four
27.3881 + fields separated from each other by one or more spaces:
27.3882 +
27.3883 + o The name of the newsgroup.
27.3884 + o The reported high water mark for the group.
27.3885 + o The reported low water mark for the group.
27.3886 + o The current status of the group on this server.
27.3887 +
27.3888 + The reported high and low water marks are as described in the GROUP
27.3889 + command (see Section 6.1.1), but note that they are in the opposite
27.3890 + order to the 211 response to that command.
27.3891 +
27.3892 + The status field is typically one of the following:
27.3893 +
27.3894 + "y" Posting is permitted.
27.3895 +
27.3896 + "n" Posting is not permitted.
27.3897 +
27.3898 + "m" Postings will be forwarded to the newsgroup moderator.
27.3899 +
27.3900 + The server SHOULD use these values when these meanings are required
27.3901 + and MUST NOT use them with any other meaning. Other values for the
27.3902 + status may exist; the definition of these other values and the
27.3903 + circumstances under which they are returned may be specified in an
27.3904 + extension or may be private to the server. A client SHOULD treat an
27.3905 + unrecognized status as giving no information.
27.3906 +
27.3907 + The status of a newsgroup only indicates how posts to that newsgroup
27.3908 + are normally processed and is not necessarily customised to the
27.3909 + specific client. For example, if the current client is forbidden
27.3910 + from posting, then this will apply equally to groups with status "y".
27.3911 + Conversely, a client with special privileges (not defined by this
27.3912 + specification) might be able to post to a group with status "n".
27.3913 +
27.3914 +
27.3915 +
27.3916 +
27.3917 +
27.3918 +
27.3919 +
27.3920 +Feather Standards Track [Page 70]
27.3921 +
27.3922 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3923 +
27.3924 +
27.3925 + For example:
27.3926 +
27.3927 + [C] LIST ACTIVE
27.3928 + [S] 215 list of newsgroups follows
27.3929 + [S] misc.test 3002322 3000234 y
27.3930 + [S] comp.risks 442001 441099 m
27.3931 + [S] alt.rfc-writers.recovery 4 1 y
27.3932 + [S] tx.natives.recovery 89 56 y
27.3933 + [S] tx.natives.recovery.d 11 9 n
27.3934 + [S] .
27.3935 +
27.3936 + or, on an implementation that includes leading zeroes:
27.3937 +
27.3938 + [C] LIST ACTIVE
27.3939 + [S] 215 list of newsgroups follows
27.3940 + [S] misc.test 0003002322 0003000234 y
27.3941 + [S] comp.risks 0000442001 0000441099 m
27.3942 + [S] alt.rfc-writers.recovery 0000000004 0000000001 y
27.3943 + [S] tx.natives.recovery 0000000089 0000000056 y
27.3944 + [S] tx.natives.recovery.d 0000000011 0000000009 n
27.3945 + [S] .
27.3946 +
27.3947 + The information is newsgroup based, and a wildmat MAY be specified,
27.3948 + in which case the response is limited to only the groups (if any)
27.3949 + whose names match the wildmat. For example:
27.3950 +
27.3951 + [C] LIST ACTIVE *.recovery
27.3952 + [S] 215 list of newsgroups follows
27.3953 + [S] alt.rfc-writers.recovery 4 1 y
27.3954 + [S] tx.natives.recovery 89 56 y
27.3955 + [S] .
27.3956 +
27.3957 +7.6.4. LIST ACTIVE.TIMES
27.3958 +
27.3959 + This keyword is optional.
27.3960 +
27.3961 + The active.times list is maintained by some NNTP servers to contain
27.3962 + information about who created a particular newsgroup and when. Each
27.3963 + line of this list consists of three fields separated from each other
27.3964 + by one or more spaces. The first field is the name of the newsgroup.
27.3965 + The second is the time when this group was created on this news
27.3966 + server, measured in seconds since the start of January 1, 1970. The
27.3967 + third is plain text intended to describe the entity that created the
27.3968 + newsgroup; it is often a mailbox as defined in RFC 2822 [RFC2822].
27.3969 + For example:
27.3970 +
27.3971 +
27.3972 +
27.3973 +
27.3974 +
27.3975 +
27.3976 +Feather Standards Track [Page 71]
27.3977 +
27.3978 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.3979 +
27.3980 +
27.3981 + [C] LIST ACTIVE.TIMES
27.3982 + [S] 215 information follows
27.3983 + [S] misc.test 930445408 <creatme@isc.org>
27.3984 + [S] alt.rfc-writers.recovery 930562309 <m@example.com>
27.3985 + [S] tx.natives.recovery 930678923 <sob@academ.com>
27.3986 + [S] .
27.3987 +
27.3988 + The list MAY omit newsgroups for which the information is unavailable
27.3989 + and MAY include groups not available on the server; in particular, it
27.3990 + MAY omit all groups created before the date and time of the oldest
27.3991 + entry. The client MUST NOT assume that the list is complete or that
27.3992 + it matches the list returned by the LIST ACTIVE command
27.3993 + (Section 7.6.3). The NEWGROUPS command (Section 7.3) may provide a
27.3994 + better way to access this information, and the results of the two
27.3995 + commands SHOULD be consistent except that, if the latter is invoked
27.3996 + with a date and time earlier than the oldest entry in active.times
27.3997 + list, its result may include extra groups.
27.3998 +
27.3999 + The information is newsgroup based, and a wildmat MAY be specified,
27.4000 + in which case the response is limited to only the groups (if any)
27.4001 + whose names match the wildmat.
27.4002 +
27.4003 +7.6.5. LIST DISTRIB.PATS
27.4004 +
27.4005 + This keyword is optional.
27.4006 +
27.4007 + The distrib.pats list is maintained by some NNTP servers to assist
27.4008 + clients to choose a value for the content of the Distribution header
27.4009 + of a news article being posted. Each line of this list consists of
27.4010 + three fields separated from each other by a colon (":"). The first
27.4011 + field is a weight, the second field is a wildmat (which may be a
27.4012 + simple newsgroup name), and the third field is a value for the
27.4013 + Distribution header content. For example:
27.4014 +
27.4015 + [C] LIST DISTRIB.PATS
27.4016 + [S] 215 information follows
27.4017 + [S] 10:local.*:local
27.4018 + [S] 5:*:world
27.4019 + [S] 20:local.here.*:thissite
27.4020 + [S] .
27.4021 +
27.4022 + The client MAY use this information to construct an appropriate
27.4023 + Distribution header given the name of a newsgroup. To do so, it
27.4024 + should determine the lines whose second field matches the newsgroup
27.4025 + name, select from among them the line with the highest weight (with 0
27.4026 + being the lowest), and use the value of the third field to construct
27.4027 + the Distribution header.
27.4028 +
27.4029 +
27.4030 +
27.4031 +
27.4032 +Feather Standards Track [Page 72]
27.4033 +
27.4034 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4035 +
27.4036 +
27.4037 + The information is not newsgroup based, and an argument MUST NOT be
27.4038 + specified.
27.4039 +
27.4040 +7.6.6. LIST NEWSGROUPS
27.4041 +
27.4042 + This keyword MUST be supported by servers advertising the READER
27.4043 + capability.
27.4044 +
27.4045 + The newsgroups list is maintained by NNTP servers to contain the name
27.4046 + of each newsgroup that is available on the server and a short
27.4047 + description about the purpose of the group. Each line of this list
27.4048 + consists of two fields separated from each other by one or more space
27.4049 + or TAB characters (the usual practice is a single TAB). The first
27.4050 + field is the name of the newsgroup, and the second is a short
27.4051 + description of the group. For example:
27.4052 +
27.4053 + [C] LIST NEWSGROUPS
27.4054 + [S] 215 information follows
27.4055 + [S] misc.test General Usenet testing
27.4056 + [S] alt.rfc-writers.recovery RFC Writers Recovery
27.4057 + [S] tx.natives.recovery Texas Natives Recovery
27.4058 + [S] .
27.4059 +
27.4060 + The list MAY omit newsgroups for which the information is unavailable
27.4061 + and MAY include groups not available on the server. The client MUST
27.4062 + NOT assume that the list is complete or that it matches the list
27.4063 + returned by LIST ACTIVE.
27.4064 +
27.4065 + The description SHOULD be in UTF-8. However, servers often obtain
27.4066 + the information from external sources. These sources may have used
27.4067 + different encodings (ones that use octets in the range 128 to 255 in
27.4068 + some other manner) and, in that case, the server MAY pass it on
27.4069 + unchanged. Therefore, clients MUST be prepared to receive such
27.4070 + descriptions.
27.4071 +
27.4072 + The information is newsgroup based, and a wildmat MAY be specified,
27.4073 + in which case the response is limited to only the groups (if any)
27.4074 + whose names match the wildmat.
27.4075 +
27.4076 +8. Article Field Access Commands
27.4077 +
27.4078 + This section lists commands that may be used to access specific
27.4079 + article fields; that is, headers of articles and metadata about
27.4080 + articles. These commands typically fetch data from an "overview
27.4081 + database", which is a database of headers extracted from incoming
27.4082 + articles plus metadata determined as the article arrives. Only
27.4083 + certain fields are included in the database.
27.4084 +
27.4085 +
27.4086 +
27.4087 +
27.4088 +Feather Standards Track [Page 73]
27.4089 +
27.4090 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4091 +
27.4092 +
27.4093 + This section is based on the Overview/NOV database [ROBE1995]
27.4094 + developed by Geoff Collyer.
27.4095 +
27.4096 +8.1. Article Metadata
27.4097 +
27.4098 + Article "metadata" is data about articles that does not occur within
27.4099 + the article itself. Each metadata item has a name that MUST begin
27.4100 + with a colon (and that MUST NOT contain a colon elsewhere within it).
27.4101 + As with header names, metadata item names are not case sensitive.
27.4102 +
27.4103 + When generating a metadata item, the server MUST compute it for
27.4104 + itself and MUST NOT trust any related value provided in the article.
27.4105 + (In particular, a Lines or Bytes header in the article MUST NOT be
27.4106 + assumed to specify the correct number of lines or bytes in the
27.4107 + article.) If the server has access to several non-identical copies
27.4108 + of an article, the value returned MUST be correct for any copy of
27.4109 + that article retrieved during the same session.
27.4110 +
27.4111 + This specification defines two metadata items: ":bytes" and ":lines".
27.4112 + Other metadata items may be defined by extensions. The names of
27.4113 + metadata items defined by registered extensions MUST NOT begin with
27.4114 + ":x-". To avoid the risk of a clash with a future registered
27.4115 + extension, the names of metadata items defined by private extensions
27.4116 + SHOULD begin with ":x-".
27.4117 +
27.4118 +8.1.1. The :bytes Metadata Item
27.4119 +
27.4120 + The :bytes metadata item for an article is a decimal integer. It
27.4121 + SHOULD equal the number of octets in the entire article: headers,
27.4122 + body, and separating empty line (counting a CRLF pair as two octets,
27.4123 + and excluding both the "." CRLF terminating the response and any "."
27.4124 + added for "dot-stuffing" purposes).
27.4125 +
27.4126 + Note to client implementers: some existing servers return a value
27.4127 + different from that above. The commonest reasons for this are as
27.4128 + follows:
27.4129 +
27.4130 + o Counting a CRLF pair as one octet.
27.4131 +
27.4132 + o Including the "." character used for dot-stuffing in the number.
27.4133 +
27.4134 + o Including the terminating "." CRLF in the number.
27.4135 +
27.4136 + o Using one copy of an article for counting the octets but then
27.4137 + returning another one that differs in some (permitted) manner.
27.4138 +
27.4139 + Implementations should be prepared for such variation and MUST NOT
27.4140 + rely on the value being accurate.
27.4141 +
27.4142 +
27.4143 +
27.4144 +Feather Standards Track [Page 74]
27.4145 +
27.4146 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4147 +
27.4148 +
27.4149 +8.1.2. The :lines Metadata Item
27.4150 +
27.4151 + The :lines metadata item for an article is a decimal integer. It
27.4152 + MUST equal the number of lines in the article body (excluding the
27.4153 + empty line separating headers and body). Equivalently, it is two
27.4154 + less than the number of CRLF pairs that the BODY command would return
27.4155 + for that article (the extra two are those following the response code
27.4156 + and the termination octet).
27.4157 +
27.4158 +8.2. Database Consistency
27.4159 +
27.4160 + The information stored in the overview database may change over time.
27.4161 + If the database records the content or absence of a given field (that
27.4162 + is, a header or metadata item) for all articles, it is said to be
27.4163 + "consistent" for that field. If it records the content of a header
27.4164 + for some articles but not for others that nevertheless included that
27.4165 + header, or if it records a metadata item for some articles but not
27.4166 + for others to which that item applies, it is said to be
27.4167 + "inconsistent" for that field.
27.4168 +
27.4169 + The LIST OVERVIEW.FMT command SHOULD list all the fields for which
27.4170 + the database is consistent at that moment. It MAY omit such fields
27.4171 + (for example, if it is not known whether the database is consistent
27.4172 + or inconsistent). It MUST NOT include fields for which the database
27.4173 + is inconsistent or that are not stored in the database. Therefore,
27.4174 + if a header appears in the LIST OVERVIEW.FMT output but not in the
27.4175 + OVER output for a given article, that header does not appear in the
27.4176 + article (similarly for metadata items).
27.4177 +
27.4178 + These rules assume that the fields being stored in the database
27.4179 + remain constant for long periods of time, and therefore the database
27.4180 + will be consistent. When the set of fields to be stored is changed,
27.4181 + it will be inconsistent until either the database is rebuilt or the
27.4182 + only articles remaining are those received since the change.
27.4183 + Therefore, the output from LIST OVERVIEW.FMT needs to be altered
27.4184 + twice. Firstly, before any fields stop being stored they MUST be
27.4185 + removed from the output; then, when the database is once more known
27.4186 + to be consistent, the new fields SHOULD be added to the output.
27.4187 +
27.4188 + If the HDR command uses the overview database rather than taking
27.4189 + information directly from the articles, the same issues of
27.4190 + consistency and inconsistency apply, and the LIST HEADERS command
27.4191 + SHOULD take the same approach as the LIST OVERVIEW.FMT command in
27.4192 + resolving them.
27.4193 +
27.4194 +
27.4195 +
27.4196 +
27.4197 +
27.4198 +
27.4199 +
27.4200 +Feather Standards Track [Page 75]
27.4201 +
27.4202 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4203 +
27.4204 +
27.4205 +8.3. OVER
27.4206 +
27.4207 +8.3.1. Usage
27.4208 +
27.4209 + Indicating capability: OVER
27.4210 +
27.4211 + Syntax
27.4212 + OVER message-id
27.4213 + OVER range
27.4214 + OVER
27.4215 +
27.4216 + Responses
27.4217 +
27.4218 + First form (message-id specified)
27.4219 + 224 Overview information follows (multi-line)
27.4220 + 430 No article with that message-id
27.4221 +
27.4222 + Second form (range specified)
27.4223 + 224 Overview information follows (multi-line)
27.4224 + 412 No newsgroup selected
27.4225 + 423 No articles in that range
27.4226 +
27.4227 + Third form (current article number used)
27.4228 + 224 Overview information follows (multi-line)
27.4229 + 412 No newsgroup selected
27.4230 + 420 Current article number is invalid
27.4231 +
27.4232 + Parameters
27.4233 + range Number(s) of articles
27.4234 + message-id Message-id of article
27.4235 +
27.4236 +8.3.2. Description
27.4237 +
27.4238 + The OVER command returns the contents of all the fields in the
27.4239 + database for an article specified by message-id, or from a specified
27.4240 + article or range of articles in the currently selected newsgroup.
27.4241 +
27.4242 + The message-id argument indicates a specific article. The range
27.4243 + argument may be any of the following:
27.4244 +
27.4245 + o An article number.
27.4246 +
27.4247 + o An article number followed by a dash to indicate all following.
27.4248 +
27.4249 + o An article number followed by a dash followed by another article
27.4250 + number.
27.4251 +
27.4252 + If neither is specified, the current article number is used.
27.4253 +
27.4254 +
27.4255 +
27.4256 +Feather Standards Track [Page 76]
27.4257 +
27.4258 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4259 +
27.4260 +
27.4261 + Support for the first (message-id) form is optional. If it is
27.4262 + supported, the OVER capability line MUST include the argument
27.4263 + "MSGID". Otherwise, the capability line MUST NOT include this
27.4264 + argument, and the OVER command MUST return the generic response code
27.4265 + 503 when this form is used.
27.4266 +
27.4267 + If the information is available, it is returned as a multi-line data
27.4268 + block following the 224 response code and contains one line per
27.4269 + article, sorted in numerical order of article number. (Note that
27.4270 + unless the argument is a range including a dash, there will be
27.4271 + exactly one line in the data block.) Each line consists of a number
27.4272 + of fields separated by a TAB. A field may be empty (in which case
27.4273 + there will be two adjacent TABs), and a sequence of trailing TABs may
27.4274 + be omitted.
27.4275 +
27.4276 + The first 8 fields MUST be the following, in order:
27.4277 +
27.4278 + "0" or article number (see below)
27.4279 + Subject header content
27.4280 + From header content
27.4281 + Date header content
27.4282 + Message-ID header content
27.4283 + References header content
27.4284 + :bytes metadata item
27.4285 + :lines metadata item
27.4286 +
27.4287 + If the article is specified by message-id (the first form of the
27.4288 + command), the article number MUST be replaced with zero, except that
27.4289 + if there is a currently selected newsgroup and the article is present
27.4290 + in that group, the server MAY use the article's number in that group.
27.4291 + (See the ARTICLE command (Section 6.2.1) and STAT examples
27.4292 + (Section 6.2.4.3) for more details.) In the other two forms of the
27.4293 + command, the article number MUST be returned.
27.4294 +
27.4295 + Any subsequent fields are the contents of the other headers and
27.4296 + metadata held in the database.
27.4297 +
27.4298 + For the five mandatory headers, the content of each field MUST be
27.4299 + based on the content of the header (that is, with the header name and
27.4300 + following colon and space removed). If the article does not contain
27.4301 + that header, or if the content is empty, the field MUST be empty.
27.4302 + For the two mandatory metadata items, the content of the field MUST
27.4303 + be just the value, with no other text.
27.4304 +
27.4305 + For all subsequent fields that contain headers, the content MUST be
27.4306 + the entire header line other than the trailing CRLF. For all
27.4307 + subsequent fields that contain metadata, the field consists of the
27.4308 + metadata name, a single space, and then the value.
27.4309 +
27.4310 +
27.4311 +
27.4312 +Feather Standards Track [Page 77]
27.4313 +
27.4314 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4315 +
27.4316 +
27.4317 + For all fields, the value is processed by first removing all CRLF
27.4318 + pairs (that is, undoing any folding and removing the terminating
27.4319 + CRLF) and then replacing each TAB with a single space. If there is
27.4320 + no such header in the article, no such metadata item, or no header or
27.4321 + item stored in the database for that article, the corresponding field
27.4322 + MUST be empty.
27.4323 +
27.4324 + Note that, after unfolding, the characters NUL, LF, and CR cannot
27.4325 + occur in the header of an article offered by a conformant server.
27.4326 + Nevertheless, servers SHOULD check for these characters and replace
27.4327 + each one by a single space (so that, for example, CR LF LF TAB will
27.4328 + become two spaces, since the CR and first LF will be removed by the
27.4329 + unfolding process). This will encourage robustness in the face of
27.4330 + non-conforming data; it is also possible that future versions of this
27.4331 + specification could permit these characters to appear in articles.
27.4332 +
27.4333 + The server SHOULD NOT produce output for articles that no longer
27.4334 + exist.
27.4335 +
27.4336 + If the argument is a message-id and no such article exists, a 430
27.4337 + response MUST be returned. If the argument is a range or is omitted
27.4338 + and the currently selected newsgroup is invalid, a 412 response MUST
27.4339 + be returned. If the argument is a range and no articles in that
27.4340 + number range exist in the currently selected newsgroup, including the
27.4341 + case where the second number is less than the first one, a 423
27.4342 + response MUST be returned. If the argument is omitted and the
27.4343 + current article number is invalid, a 420 response MUST be returned.
27.4344 +
27.4345 +8.3.3. Examples
27.4346 +
27.4347 + In the first four examples, TAB has been replaced by vertical bar and
27.4348 + some lines have been folded for readability.
27.4349 +
27.4350 + Example of a successful retrieval of overview information for an
27.4351 + article (explicitly not using an article number):
27.4352 +
27.4353 + [C] GROUP misc.test
27.4354 + [S] 211 1234 3000234 3002322 misc.test
27.4355 + [C] OVER
27.4356 + [S] 224 Overview information follows
27.4357 + [S] 3000234|I am just a test article|"Demo User"
27.4358 + <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
27.4359 + <45223423@example.com>|<45454@example.net>|1234|
27.4360 + 17|Xref: news.example.com misc.test:3000363
27.4361 + [S] .
27.4362 +
27.4363 +
27.4364 +
27.4365 +
27.4366 +
27.4367 +
27.4368 +Feather Standards Track [Page 78]
27.4369 +
27.4370 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4371 +
27.4372 +
27.4373 + Example of a successful retrieval of overview information for an
27.4374 + article by message-id:
27.4375 +
27.4376 + [C] CAPABILITIES
27.4377 + [S] 101 Capability list:
27.4378 + [S] VERSION 2
27.4379 + [S] READER
27.4380 + [S] OVER MSGID
27.4381 + [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
27.4382 + [S] .
27.4383 + [C] OVER <45223423@example.com>
27.4384 + [S] 224 Overview information follows
27.4385 + [S] 0|I am just a test article|"Demo User"
27.4386 + <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
27.4387 + <45223423@example.com>|<45454@example.net>|1234|
27.4388 + 17|Xref: news.example.com misc.test:3000363
27.4389 + [S] .
27.4390 +
27.4391 + Note that the article number has been replaced by "0".
27.4392 +
27.4393 + Example of the same commands on a system that does not implement
27.4394 + retrieval by message-id:
27.4395 +
27.4396 + [C] CAPABILITIES
27.4397 + [S] 101 Capability list:
27.4398 + [S] VERSION 2
27.4399 + [S] READER
27.4400 + [S] OVER
27.4401 + [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
27.4402 + [S] .
27.4403 + [C] OVER <45223423@example.com>
27.4404 + [S] 503 Overview by message-id unsupported
27.4405 +
27.4406 +
27.4407 +
27.4408 +
27.4409 +
27.4410 +
27.4411 +
27.4412 +
27.4413 +
27.4414 +
27.4415 +
27.4416 +
27.4417 +
27.4418 +
27.4419 +
27.4420 +
27.4421 +
27.4422 +
27.4423 +
27.4424 +Feather Standards Track [Page 79]
27.4425 +
27.4426 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4427 +
27.4428 +
27.4429 + Example of a successful retrieval of overview information for a range
27.4430 + of articles:
27.4431 +
27.4432 + [C] GROUP misc.test
27.4433 + [S] 211 1234 3000234 3002322 misc.test
27.4434 + [C] OVER 3000234-3000240
27.4435 + [S] 224 Overview information follows
27.4436 + [S] 3000234|I am just a test article|"Demo User"
27.4437 + <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
27.4438 + <45223423@example.com>|<45454@example.net>|1234|
27.4439 + 17|Xref: news.example.com misc.test:3000363
27.4440 + [S] 3000235|Another test article|nobody@nowhere.to
27.4441 + (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>||
27.4442 + 4818|37||Distribution: fi
27.4443 + [S] 3000238|Re: I am just a test article|somebody@elsewhere.to|
27.4444 + 7 Oct 1998 11:38:40 +1200|<kfwer3v@elsewhere.to>|
27.4445 + <45223423@to.to>|9234|51
27.4446 + [S] .
27.4447 +
27.4448 + Note the missing "References" and Xref headers in the second line,
27.4449 + the missing trailing fields in the first and last lines, and that
27.4450 + there are only results for those articles that still exist.
27.4451 +
27.4452 + Example of an unsuccessful retrieval of overview information on an
27.4453 + article by number:
27.4454 +
27.4455 + [C] GROUP misc.test
27.4456 + [S] 211 1234 3000234 3002322 misc.test
27.4457 + [C] OVER 300256
27.4458 + [S] 423 No such article in this group
27.4459 +
27.4460 + Example of an invalid range:
27.4461 +
27.4462 + [C] GROUP misc.test
27.4463 + [S] 211 1234 3000234 3002322 misc.test
27.4464 + [C] OVER 3000444-3000222
27.4465 + [S] 423 Empty range
27.4466 +
27.4467 + Example of an unsuccessful retrieval of overview information by
27.4468 + number because no newsgroup was selected first:
27.4469 +
27.4470 + [Assumes currently selected newsgroup is invalid.]
27.4471 + [C] OVER
27.4472 + [S] 412 No newsgroup selected
27.4473 +
27.4474 +
27.4475 +
27.4476 +
27.4477 +
27.4478 +
27.4479 +
27.4480 +Feather Standards Track [Page 80]
27.4481 +
27.4482 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4483 +
27.4484 +
27.4485 + Example of an attempt to retrieve information when the currently
27.4486 + selected newsgroup is empty:
27.4487 +
27.4488 + [C] GROUP example.empty.newsgroup
27.4489 + [S] 211 0 0 0 example.empty.newsgroup
27.4490 + [C] OVER
27.4491 + [S] 420 No current article selected
27.4492 +
27.4493 +8.4. LIST OVERVIEW.FMT
27.4494 +
27.4495 +8.4.1. Usage
27.4496 +
27.4497 + Indicating capability: OVER
27.4498 +
27.4499 + Syntax
27.4500 + LIST OVERVIEW.FMT
27.4501 +
27.4502 + Responses
27.4503 + 215 Information follows (multi-line)
27.4504 +
27.4505 +8.4.2. Description
27.4506 +
27.4507 + See Section 7.6.1 for general requirements of the LIST command.
27.4508 +
27.4509 + The LIST OVERVIEW.FMT command returns a description of the fields in
27.4510 + the database for which it is consistent (as described above). The
27.4511 + information is returned as a multi-line data block following the 215
27.4512 + response code. The information contains one line per field in the
27.4513 + order in which they are returned by the OVER command; the first 7
27.4514 + lines MUST (except for the case of letters) be exactly as follows:
27.4515 +
27.4516 + Subject:
27.4517 + From:
27.4518 + Date:
27.4519 + Message-ID:
27.4520 + References:
27.4521 + :bytes
27.4522 + :lines
27.4523 +
27.4524 + For compatibility with existing implementations, the last two lines
27.4525 + MAY instead be:
27.4526 +
27.4527 + Bytes:
27.4528 + Lines:
27.4529 +
27.4530 + even though they refer to metadata, not headers.
27.4531 +
27.4532 +
27.4533 +
27.4534 +
27.4535 +
27.4536 +Feather Standards Track [Page 81]
27.4537 +
27.4538 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4539 +
27.4540 +
27.4541 + All subsequent lines MUST consist of either a header name followed by
27.4542 + ":full", or the name of a piece of metadata.
27.4543 +
27.4544 + There are no leading or trailing spaces in the output.
27.4545 +
27.4546 + Note that the 7 fixed lines describe the 2nd to 8th fields of the
27.4547 + OVER output. The "full" suffix (which may use either uppercase,
27.4548 + lowercase, or a mix) is a reminder that the corresponding fields
27.4549 + include the header name.
27.4550 +
27.4551 + This command MAY generate different results if it is used more than
27.4552 + once in a session.
27.4553 +
27.4554 + If the OVER command is not implemented, the meaning of the output
27.4555 + from this command is not specified, but it must still meet the above
27.4556 + syntactic requirements.
27.4557 +
27.4558 +8.4.3. Examples
27.4559 +
27.4560 + Example of LIST OVERVIEW.FMT output corresponding to the example OVER
27.4561 + output above, in the preferred format:
27.4562 +
27.4563 + [C] LIST OVERVIEW.FMT
27.4564 + [S] 215 Order of fields in overview database.
27.4565 + [S] Subject:
27.4566 + [S] From:
27.4567 + [S] Date:
27.4568 + [S] Message-ID:
27.4569 + [S] References:
27.4570 + [S] :bytes
27.4571 + [S] :lines
27.4572 + [S] Xref:full
27.4573 + [S] Distribution:full
27.4574 + [S] .
27.4575 +
27.4576 +
27.4577 +
27.4578 +
27.4579 +
27.4580 +
27.4581 +
27.4582 +
27.4583 +
27.4584 +
27.4585 +
27.4586 +
27.4587 +
27.4588 +
27.4589 +
27.4590 +
27.4591 +
27.4592 +Feather Standards Track [Page 82]
27.4593 +
27.4594 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4595 +
27.4596 +
27.4597 + Example of LIST OVERVIEW.FMT output corresponding to the example OVER
27.4598 + output above, in the alternative format:
27.4599 +
27.4600 + [C] LIST OVERVIEW.FMT
27.4601 + [S] 215 Order of fields in overview database.
27.4602 + [S] Subject:
27.4603 + [S] From:
27.4604 + [S] Date:
27.4605 + [S] Message-ID:
27.4606 + [S] References:
27.4607 + [S] Bytes:
27.4608 + [S] Lines:
27.4609 + [S] Xref:FULL
27.4610 + [S] Distribution:FULL
27.4611 + [S] .
27.4612 +
27.4613 +8.5. HDR
27.4614 +
27.4615 +8.5.1. Usage
27.4616 +
27.4617 + Indicating capability: HDR
27.4618 +
27.4619 + Syntax
27.4620 + HDR field message-id
27.4621 + HDR field range
27.4622 + HDR field
27.4623 +
27.4624 + Responses
27.4625 +
27.4626 + First form (message-id specified)
27.4627 + 225 Headers follow (multi-line)
27.4628 + 430 No article with that message-id
27.4629 +
27.4630 + Second form (range specified)
27.4631 + 225 Headers follow (multi-line)
27.4632 + 412 No newsgroup selected
27.4633 + 423 No articles in that range
27.4634 +
27.4635 + Third form (current article number used)
27.4636 + 225 Headers follow (multi-line)
27.4637 + 412 No newsgroup selected
27.4638 + 420 Current article number is invalid
27.4639 +
27.4640 + Parameters
27.4641 + field Name of field
27.4642 + range Number(s) of articles
27.4643 + message-id Message-id of article
27.4644 +
27.4645 +
27.4646 +
27.4647 +
27.4648 +Feather Standards Track [Page 83]
27.4649 +
27.4650 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4651 +
27.4652 +
27.4653 +8.5.2. Description
27.4654 +
27.4655 + The HDR command provides access to specific fields from an article
27.4656 + specified by message-id, or from a specified article or range of
27.4657 + articles in the currently selected newsgroup. It MAY take the
27.4658 + information directly from the articles or from the overview database.
27.4659 + In the case of headers, an implementation MAY restrict the use of
27.4660 + this command to a specific list of headers or MAY allow it to be used
27.4661 + with any header; it may behave differently when it is used with a
27.4662 + message-id argument and when it is used with a range or no argument.
27.4663 +
27.4664 + The required field argument is the name of a header with the colon
27.4665 + omitted (e.g., "subject") or the name of a metadata item including
27.4666 + the leading colon (e.g., ":bytes"), and is case insensitive.
27.4667 +
27.4668 + The message-id argument indicates a specific article. The range
27.4669 + argument may be any of the following:
27.4670 +
27.4671 + o An article number.
27.4672 +
27.4673 + o An article number followed by a dash to indicate all following.
27.4674 +
27.4675 + o An article number followed by a dash followed by another article
27.4676 + number.
27.4677 +
27.4678 + If neither is specified, the current article number is used.
27.4679 +
27.4680 + If the information is available, it is returned as a multi-line data
27.4681 + block following the 225 response code and contains one line for each
27.4682 + article in the range that exists. (Note that unless the argument is
27.4683 + a range including a dash, there will be exactly one line in the data
27.4684 + block.) The line consists of the article number, a space, and then
27.4685 + the contents of the field. In the case of a header, the header name,
27.4686 + the colon, and the first space after the colon are all omitted.
27.4687 +
27.4688 + If the article is specified by message-id (the first form of the
27.4689 + command), the article number MUST be replaced with zero, except that
27.4690 + if there is a currently selected newsgroup and the article is present
27.4691 + in that group, the server MAY use the article's number in that group.
27.4692 + (See the ARTICLE command (Section 6.2.1) and STAT examples
27.4693 + (Section 6.2.4.3) for more details.) In the other two forms of the
27.4694 + command, the article number MUST be returned.
27.4695 +
27.4696 + Header contents are modified as follows: all CRLF pairs are removed,
27.4697 + and then each TAB is replaced with a single space. (Note that this
27.4698 + is the same transformation as is performed by the OVER command
27.4699 + (Section 8.3.2), and the same comment concerning NUL, CR, and LF
27.4700 + applies.)
27.4701 +
27.4702 +
27.4703 +
27.4704 +Feather Standards Track [Page 84]
27.4705 +
27.4706 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4707 +
27.4708 +
27.4709 + Note the distinction between headers and metadata appearing to have
27.4710 + the same meaning. Headers are always taken unchanged from the
27.4711 + article; metadata are always calculated. For example, a request for
27.4712 + "Lines" returns the contents of the "Lines" header of the specified
27.4713 + articles, if any, no matter whether they accurately state the number
27.4714 + of lines, while a request for ":lines" returns the line count
27.4715 + metadata, which is always the actual number of lines irrespective of
27.4716 + what any header may state.
27.4717 +
27.4718 + If the requested header is not present in the article, or if it is
27.4719 + present but empty, a line for that article is included in the output,
27.4720 + but the header content portion of the line is empty (the space after
27.4721 + the article number MAY be retained or omitted). If the header occurs
27.4722 + in a given article more than once, only the content of the first
27.4723 + occurrence is returned by HDR. If any article number in the provided
27.4724 + range does not exist in the group, no line for that article number is
27.4725 + included in the output.
27.4726 +
27.4727 + If the second argument is a message-id and no such article exists, a
27.4728 + 430 response MUST be returned. If the second argument is a range or
27.4729 + is omitted and the currently selected newsgroup is invalid, a 412
27.4730 + response MUST be returned. If the second argument is a range and no
27.4731 + articles in that number range exist in the currently selected
27.4732 + newsgroup, including the case where the second number is less than
27.4733 + the first one, a 423 response MUST be returned. If the second
27.4734 + argument is omitted and the current article number is invalid, a 420
27.4735 + response MUST be returned.
27.4736 +
27.4737 + A server MAY only allow HDR commands for a limited set of fields; it
27.4738 + may behave differently in this respect for the first (message-id)
27.4739 + form from how it would for the other forms. If so, it MUST respond
27.4740 + with the generic 503 response to attempts to request other fields,
27.4741 + rather than return erroneous results, such as a successful empty
27.4742 + response.
27.4743 +
27.4744 + If HDR uses the overview database and it is inconsistent for the
27.4745 + requested field, the server MAY return what results it can, or it MAY
27.4746 + respond with the generic 503 response. In the latter case, the field
27.4747 + MUST NOT appear in the output from LIST HEADERS.
27.4748 +
27.4749 +
27.4750 +
27.4751 +
27.4752 +
27.4753 +
27.4754 +
27.4755 +
27.4756 +
27.4757 +
27.4758 +
27.4759 +
27.4760 +Feather Standards Track [Page 85]
27.4761 +
27.4762 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4763 +
27.4764 +
27.4765 +8.5.3. Examples
27.4766 +
27.4767 + Example of a successful retrieval of subject lines from a range of
27.4768 + articles (3000235 has no Subject header, and 3000236 is missing):
27.4769 +
27.4770 + [C] GROUP misc.test
27.4771 + [S] 211 1234 3000234 3002322 misc.test
27.4772 + [C] HDR Subject 3000234-3000238
27.4773 + [S] 225 Headers follow
27.4774 + [S] 3000234 I am just a test article
27.4775 + [S] 3000235
27.4776 + [S] 3000237 Re: I am just a test article
27.4777 + [S] 3000238 Ditto
27.4778 + [S] .
27.4779 +
27.4780 + Example of a successful retrieval of line counts from a range of
27.4781 + articles:
27.4782 +
27.4783 + [C] GROUP misc.test
27.4784 + [S] 211 1234 3000234 3002322 misc.test
27.4785 + [C] HDR :lines 3000234-3000238
27.4786 + [S] 225 Headers follow
27.4787 + [S] 3000234 42
27.4788 + [S] 3000235 5
27.4789 + [S] 3000237 11
27.4790 + [S] 3000238 2378
27.4791 + [S] .
27.4792 +
27.4793 + Example of a successful retrieval of the subject line from an article
27.4794 + by message-id:
27.4795 +
27.4796 + [C] GROUP misc.test
27.4797 + [S] 211 1234 3000234 3002322 misc.test
27.4798 + [C] HDR subject <i.am.a.test.article@example.com>
27.4799 + [S] 225 Header information follows
27.4800 + [S] 0 I am just a test article
27.4801 + [S] .
27.4802 +
27.4803 + Example of a successful retrieval of the subject line from the
27.4804 + current article:
27.4805 +
27.4806 + [C] GROUP misc.test
27.4807 + [S] 211 1234 3000234 3002322 misc.test
27.4808 + [C] HDR subject
27.4809 + [S] 225 Header information follows
27.4810 + [S] 3000234 I am just a test article
27.4811 + [S] .
27.4812 +
27.4813 +
27.4814 +
27.4815 +
27.4816 +Feather Standards Track [Page 86]
27.4817 +
27.4818 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4819 +
27.4820 +
27.4821 + Example of an unsuccessful retrieval of a header from an article by
27.4822 + message-id:
27.4823 +
27.4824 + [C] HDR subject <i.am.not.there@example.com>
27.4825 + [S] 430 No Such Article Found
27.4826 +
27.4827 + Example of an unsuccessful retrieval of headers from articles by
27.4828 + number because no newsgroup was selected first:
27.4829 +
27.4830 + [Assumes currently selected newsgroup is invalid.]
27.4831 + [C] HDR subject 300256-
27.4832 + [S] 412 No newsgroup selected
27.4833 +
27.4834 + Example of an unsuccessful retrieval of headers because the currently
27.4835 + selected newsgroup is empty:
27.4836 +
27.4837 + [C] GROUP example.empty.newsgroup
27.4838 + [S] 211 0 0 0 example.empty.newsgroup
27.4839 + [C] HDR subject 1-
27.4840 + [S] 423 No articles in that range
27.4841 +
27.4842 + Example of an unsuccessful retrieval of headers because the server
27.4843 + does not allow HDR commands for that header:
27.4844 +
27.4845 + [C] GROUP misc.test
27.4846 + [S] 211 1234 3000234 3002322 misc.test
27.4847 + [C] HDR Content-Type 3000234-3000238
27.4848 + [S] 503 HDR not permitted on Content-Type
27.4849 +
27.4850 +8.6. LIST HEADERS
27.4851 +
27.4852 +8.6.1. Usage
27.4853 +
27.4854 + Indicating capability: HDR
27.4855 +
27.4856 + Syntax
27.4857 + LIST HEADERS [MSGID|RANGE]
27.4858 +
27.4859 + Responses
27.4860 + 215 Field list follows (multi-line)
27.4861 +
27.4862 + Parameters
27.4863 + MSGID Requests list for access by message-id
27.4864 + RANGE Requests list for access by range
27.4865 +
27.4866 +
27.4867 +
27.4868 +
27.4869 +
27.4870 +
27.4871 +
27.4872 +Feather Standards Track [Page 87]
27.4873 +
27.4874 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4875 +
27.4876 +
27.4877 +8.6.2. Description
27.4878 +
27.4879 + See Section 7.6.1 for general requirements of the LIST command.
27.4880 +
27.4881 + The LIST HEADERS command returns a list of fields that may be
27.4882 + retrieved using the HDR command.
27.4883 +
27.4884 + The information is returned as a multi-line data block following the
27.4885 + 215 response code and contains one line for each field name
27.4886 + (excluding the trailing colon for headers and including the leading
27.4887 + colon for metadata items). If the implementation allows any header
27.4888 + to be retrieved, it MUST NOT include any header names in the list but
27.4889 + MUST include the special entry ":" (a single colon on its own). It
27.4890 + MUST still explicitly list any metadata items that are available.
27.4891 + The order of items in the list is not significant; the server need
27.4892 + not even consistently return the same order. The list MAY be empty
27.4893 + (though in this circumstance there is little point in providing the
27.4894 + HDR command).
27.4895 +
27.4896 + An implementation that also supports the OVER command SHOULD at least
27.4897 + permit all the headers and metadata items listed in the output from
27.4898 + the LIST OVERVIEW.FMT command.
27.4899 +
27.4900 + If the server treats the first form of the HDR command (message-id
27.4901 + specified) differently from the other two forms (range specified or
27.4902 + current article number used) in respect of which headers or metadata
27.4903 + items are available, then the following apply:
27.4904 +
27.4905 + o If the MSGID argument is specified, the results MUST be those
27.4906 + available for the first form of the HDR command.
27.4907 +
27.4908 + o If the RANGE argument is specified, the results MUST be those
27.4909 + available for the second and third forms of the HDR command.
27.4910 +
27.4911 + o If no argument is specified, the results MUST be those available
27.4912 + in all forms of the HDR command (that is, it MUST only list those
27.4913 + items listed in both the previous cases).
27.4914 +
27.4915 + If the server does not treat the various forms differently, then it
27.4916 + MUST ignore any argument and always produce the same results (though
27.4917 + not necessarily always in the same order).
27.4918 +
27.4919 + If the HDR command is not implemented, the meaning of the output from
27.4920 + this command is not specified, but it must still meet the above
27.4921 + syntactic requirements.
27.4922 +
27.4923 +
27.4924 +
27.4925 +
27.4926 +
27.4927 +
27.4928 +Feather Standards Track [Page 88]
27.4929 +
27.4930 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4931 +
27.4932 +
27.4933 +8.6.3. Examples
27.4934 +
27.4935 + Example of an implementation providing access to only a few headers:
27.4936 +
27.4937 + [C] LIST HEADERS
27.4938 + [S] 215 headers supported:
27.4939 + [S] Subject
27.4940 + [S] Message-ID
27.4941 + [S] Xref
27.4942 + [S] .
27.4943 +
27.4944 + Example of an implementation providing access to the same fields as
27.4945 + the first example in Section 8.4.3:
27.4946 +
27.4947 + [C] CAPABILITIES
27.4948 + [S] 101 Capability list:
27.4949 + [S] VERSION 2
27.4950 + [S] READER
27.4951 + [S] OVER
27.4952 + [S] HDR
27.4953 + [S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT
27.4954 + [S] .
27.4955 + [C] LIST HEADERS
27.4956 + [S] 215 headers and metadata items supported:
27.4957 + [S] Date
27.4958 + [S] Distribution
27.4959 + [S] From
27.4960 + [S] Message-ID
27.4961 + [S] References
27.4962 + [S] Subject
27.4963 + [S] Xref
27.4964 + [S] :bytes
27.4965 + [S] :lines
27.4966 + [S] .
27.4967 +
27.4968 + Example of an implementation providing access to all headers:
27.4969 +
27.4970 + [C] LIST HEADERS
27.4971 + [S] 215 metadata items supported:
27.4972 + [S] :
27.4973 + [S] :lines
27.4974 + [S] :bytes
27.4975 + [S] :x-article-number
27.4976 + [S] .
27.4977 +
27.4978 +
27.4979 +
27.4980 +
27.4981 +
27.4982 +
27.4983 +
27.4984 +Feather Standards Track [Page 89]
27.4985 +
27.4986 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.4987 +
27.4988 +
27.4989 + Example of an implementation distinguishing the first form of the HDR
27.4990 + command from the other two forms:
27.4991 +
27.4992 + [C] LIST HEADERS RANGE
27.4993 + [S] 215 metadata items supported:
27.4994 + [S] :
27.4995 + [S] :lines
27.4996 + [S] :bytes
27.4997 + [S] .
27.4998 + [C] LIST HEADERS MSGID
27.4999 + [S] 215 headers and metadata items supported:
27.5000 + [S] Date
27.5001 + [S] Distribution
27.5002 + [S] From
27.5003 + [S] Message-ID
27.5004 + [S] References
27.5005 + [S] Subject
27.5006 + [S] :lines
27.5007 + [S] :bytes
27.5008 + [S] :x-article-number
27.5009 + [S] .
27.5010 + [C] LIST HEADERS
27.5011 + [S] 215 headers and metadata items supported:
27.5012 + [S] Date
27.5013 + [S] Distribution
27.5014 + [S] From
27.5015 + [S] Message-ID
27.5016 + [S] References
27.5017 + [S] Subject
27.5018 + [S] :lines
27.5019 + [S] :bytes
27.5020 + [S] .
27.5021 +
27.5022 + Note that :x-article-number does not appear in the last set of
27.5023 + output.
27.5024 +
27.5025 +9. Augmented BNF Syntax for NNTP
27.5026 +
27.5027 +9.1. Introduction
27.5028 +
27.5029 + Each of the following sections describes the syntax of a major
27.5030 + element of NNTP. This syntax extends and refines the descriptions
27.5031 + elsewhere in this specification and should be given precedence when
27.5032 + resolving apparent conflicts. Note that ABNF [RFC4234] strings are
27.5033 + case insensitive. Non-terminals used in several places are defined
27.5034 + in a separate section at the end.
27.5035 +
27.5036 +
27.5037 +
27.5038 +
27.5039 +
27.5040 +Feather Standards Track [Page 90]
27.5041 +
27.5042 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5043 +
27.5044 +
27.5045 + Between them, the non-terminals <command-line>, <command-datastream>,
27.5046 + <command-continuation>, and <response> specify the text that flows
27.5047 + between client and server. A consistent naming scheme is used in
27.5048 + this document for the non-terminals relating to each command, and
27.5049 + SHOULD be used by the specification of registered extensions.
27.5050 +
27.5051 + For each command, the sequence is as follows:
27.5052 +
27.5053 + o The client sends an instance of <command-line>; the syntax for the
27.5054 + EXAMPLE command is <example-command>.
27.5055 +
27.5056 + o If the client is one that immediately streams data, it sends an
27.5057 + instance of <command-datastream>; the syntax for the EXAMPLE
27.5058 + command is <example-datastream>.
27.5059 +
27.5060 + o The server sends an instance of <response>.
27.5061 +
27.5062 + * The initial response line is independent of the command that
27.5063 + generated it; if the 000 response has arguments, the syntax of
27.5064 + the initial line is <response-000-content>.
27.5065 +
27.5066 + * If the response is multi-line, the initial line is followed by
27.5067 + a <multi-line-data-block>. The syntax for the contents of this
27.5068 + block after "dot-stuffing" has been removed is (for the 000
27.5069 + response to the EXAMPLE command) <example-000-ml-content> and
27.5070 + is an instance of <multi-line-response-content>.
27.5071 +
27.5072 + o While the latest response is one that indicates more data is
27.5073 + required (in general, a 3xx response):
27.5074 +
27.5075 + * the client sends an instance of <command-continuation>; the
27.5076 + syntax for the EXAMPLE continuation following a 333 response is
27.5077 + <example-333-continuation>;
27.5078 +
27.5079 + * the server sends another instance of <response>, as above.
27.5080 +
27.5081 + (There are no commands in this specification that immediately stream
27.5082 + data, but this non-terminal is defined for the convenience of
27.5083 + extensions.)
27.5084 +
27.5085 +
27.5086 +
27.5087 +
27.5088 +
27.5089 +
27.5090 +
27.5091 +
27.5092 +
27.5093 +
27.5094 +
27.5095 +
27.5096 +Feather Standards Track [Page 91]
27.5097 +
27.5098 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5099 +
27.5100 +
27.5101 +9.2. Commands
27.5102 +
27.5103 + This syntax defines the non-terminal <command-line>, which represents
27.5104 + what is sent from the client to the server (see section 3.1 for
27.5105 + limits on lengths).
27.5106 +
27.5107 + command-line = command EOL
27.5108 + command = X-command
27.5109 + X-command = keyword *(WS token)
27.5110 +
27.5111 + command =/ article-command /
27.5112 + body-command /
27.5113 + capabilities-command /
27.5114 + date-command /
27.5115 + group-command /
27.5116 + hdr-command /
27.5117 + head-command /
27.5118 + help-command /
27.5119 + ihave-command /
27.5120 + last-command /
27.5121 + list-command /
27.5122 + listgroup-command /
27.5123 + mode-reader-command /
27.5124 + newgroups-command /
27.5125 + newnews-command /
27.5126 + next-command /
27.5127 + over-command /
27.5128 + post-command /
27.5129 + quit-command /
27.5130 + stat-command
27.5131 +
27.5132 + article-command = "ARTICLE" [WS article-ref]
27.5133 + body-command = "BODY" [WS article-ref]
27.5134 + capabilities-command = "CAPABILITIES" [WS keyword]
27.5135 + date-command = "DATE"
27.5136 + group-command = "GROUP" [WS newsgroup-name]
27.5137 + hdr-command = "HDR" WS header-meta-name [WS range-ref]
27.5138 + head-command = "HEAD" [WS article-ref]
27.5139 + help-command = "HELP"
27.5140 + ihave-command = "IHAVE" WS message-id
27.5141 + last-command = "LAST"
27.5142 + list-command = "LIST" [WS list-arguments]
27.5143 + listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]]
27.5144 + mode-reader-command = "MODE" WS "READER"
27.5145 + newgroups-command = "NEWGROUPS" WS date-time
27.5146 + newnews-command = "NEWNEWS" WS wildmat WS date-time
27.5147 + next-command = "NEXT"
27.5148 + over-command = "OVER" [WS range-ref]
27.5149 +
27.5150 +
27.5151 +
27.5152 +Feather Standards Track [Page 92]
27.5153 +
27.5154 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5155 +
27.5156 +
27.5157 + post-command = "POST"
27.5158 + quit-command = "QUIT"
27.5159 + stat-command = "STAT" [WS article-ref]
27.5160 +
27.5161 + article-ref = article-number / message-id
27.5162 + date = date2y / date4y
27.5163 + date4y = 4DIGIT 2DIGIT 2DIGIT
27.5164 + date2y = 2DIGIT 2DIGIT 2DIGIT
27.5165 + date-time = date WS time [WS "GMT"]
27.5166 + header-meta-name = header-name / metadata-name
27.5167 + list-arguments = keyword [WS token]
27.5168 + metadata-name = ":" 1*A-NOTCOLON
27.5169 + range = article-number ["-" [article-number]]
27.5170 + range-ref = range / message-id
27.5171 + time = 2DIGIT 2DIGIT 2DIGIT
27.5172 +
27.5173 +9.3. Command Continuation
27.5174 +
27.5175 + This syntax defines the further material sent by the client in the
27.5176 + case of multi-stage commands and those that stream data.
27.5177 +
27.5178 + command-datastream = UNDEFINED
27.5179 + ; not used, provided as a hook for extensions
27.5180 + command-continuation = ihave-335-continuation /
27.5181 + post-340-continuation
27.5182 +
27.5183 + ihave-335-continuation = encoded-article
27.5184 + post-340-continuation = encoded-article
27.5185 +
27.5186 + encoded-article = multi-line-data-block
27.5187 + ; after undoing the "dot-stuffing", this MUST match <article>
27.5188 +
27.5189 +9.4. Responses
27.5190 +
27.5191 +9.4.1. Generic Responses
27.5192 +
27.5193 + This syntax defines the non-terminal <response>, which represents the
27.5194 + generic form of responses; that is, what is sent from the server to
27.5195 + the client in response to a <command> or a <command-continuation>.
27.5196 +
27.5197 + response = simple-response / multi-line-response
27.5198 + simple-response = initial-response-line
27.5199 + multi-line-response = initial-response-line multi-line-data-block
27.5200 +
27.5201 + initial-response-line =
27.5202 + initial-response-content [SP trailing-comment] CRLF
27.5203 + initial-response-content = X-initial-response-content
27.5204 + X-initial-response-content = 3DIGIT *(SP response-argument)
27.5205 +
27.5206 +
27.5207 +
27.5208 +Feather Standards Track [Page 93]
27.5209 +
27.5210 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5211 +
27.5212 +
27.5213 + response-argument = 1*A-CHAR
27.5214 + trailing-comment = *U-CHAR
27.5215 +
27.5216 +9.4.2. Initial Response Line Contents
27.5217 +
27.5218 + This syntax defines the specific initial response lines for the
27.5219 + various commands in this specification (see section 3.1 for limits on
27.5220 + lengths). Only those response codes with arguments are listed.
27.5221 +
27.5222 + initial-response-content =/ response-111-content /
27.5223 + response-211-content /
27.5224 + response-220-content /
27.5225 + response-221-content /
27.5226 + response-222-content /
27.5227 + response-223-content /
27.5228 + response-401-content
27.5229 +
27.5230 + response-111-content = "111" SP date4y time
27.5231 + response-211-content = "211" 3(SP article-number) SP newsgroup-name
27.5232 + response-220-content = "220" SP article-number SP message-id
27.5233 + response-221-content = "221" SP article-number SP message-id
27.5234 + response-222-content = "222" SP article-number SP message-id
27.5235 + response-223-content = "223" SP article-number SP message-id
27.5236 + response-401-content = "401" SP capability-label
27.5237 +
27.5238 +9.4.3. Multi-line Response Contents
27.5239 +
27.5240 + This syntax defines the content of the various multi-line responses;
27.5241 + more precisely, it defines the part of the response in the multi-line
27.5242 + data block after any "dot-stuffing" has been undone. The numeric
27.5243 + portion of each non-terminal name indicates the response code that is
27.5244 + followed by this data.
27.5245 +
27.5246 + multi-line-response-content = article-220-ml-content /
27.5247 + body-222-ml-content /
27.5248 + capabilities-101-ml-content /
27.5249 + hdr-225-ml-content /
27.5250 + head-221-ml-content /
27.5251 + help-100-ml-content /
27.5252 + list-215-ml-content /
27.5253 + listgroup-211-ml-content /
27.5254 + newgroups-231-ml-content /
27.5255 + newnews-230-ml-content /
27.5256 + over-224-ml-content
27.5257 +
27.5258 + article-220-ml-content = article
27.5259 + body-222-ml-content = body
27.5260 + capabilities-101-ml-content = version-line CRLF
27.5261 +
27.5262 +
27.5263 +
27.5264 +Feather Standards Track [Page 94]
27.5265 +
27.5266 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5267 +
27.5268 +
27.5269 + *(capability-line CRLF)
27.5270 + hdr-225-ml-content = *(article-number SP hdr-content CRLF)
27.5271 + head-221-ml-content = 1*header
27.5272 + help-100-ml-content = *(*U-CHAR CRLF)
27.5273 + list-215-ml-content = list-content
27.5274 + listgroup-211-ml-content = *(article-number CRLF)
27.5275 + newgroups-231-ml-content = active-groups-list
27.5276 + newnews-230-ml-content = *(message-id CRLF)
27.5277 + over-224-ml-content = *(article-number over-content CRLF)
27.5278 +
27.5279 + active-groups-list = *(newsgroup-name SPA article-number
27.5280 + SPA article-number SPA newsgroup-status CRLF)
27.5281 + hdr-content = *S-NONTAB
27.5282 + hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content]
27.5283 + list-content = body
27.5284 + newsgroup-status = %x79 / %x6E / %x6D / private-status
27.5285 + over-content = 1*6(TAB hdr-content) /
27.5286 + 7(TAB hdr-content) *(TAB hdr-n-content)
27.5287 + private-status = token ; except the values in newsgroup-status
27.5288 +
27.5289 +9.5. Capability Lines
27.5290 +
27.5291 + This syntax defines the generic form of a capability line in the
27.5292 + capabilities list (see Section 3.3.1).
27.5293 +
27.5294 + capability-line = capability-entry
27.5295 + capability-entry = X-capability-entry
27.5296 + X-capability-entry = capability-label *(WS capability-argument)
27.5297 + capability-label = keyword
27.5298 + capability-argument = token
27.5299 +
27.5300 + This syntax defines the specific capability entries for the
27.5301 + capabilities in this specification.
27.5302 +
27.5303 + capability-entry =/
27.5304 + hdr-capability /
27.5305 + ihave-capability /
27.5306 + implementation-capability /
27.5307 + list-capability /
27.5308 + mode-reader-capability /
27.5309 + newnews-capability /
27.5310 + over-capability /
27.5311 + post-capability /
27.5312 + reader-capability
27.5313 +
27.5314 + hdr-capability = "HDR"
27.5315 + ihave-capability = "IHAVE"
27.5316 + implementation-capability = "IMPLEMENTATION" *(WS token)
27.5317 +
27.5318 +
27.5319 +
27.5320 +Feather Standards Track [Page 95]
27.5321 +
27.5322 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5323 +
27.5324 +
27.5325 + list-capability = "LIST" 1*(WS keyword)
27.5326 + mode-reader-capability = "MODE-READER"
27.5327 + newnews-capability = "NEWNEWS"
27.5328 + over-capability = "OVER" [WS "MSGID"]
27.5329 + post-capability = "POST"
27.5330 + reader-capability = "READER"
27.5331 +
27.5332 + version-line = "VERSION" 1*(WS version-number)
27.5333 + version-number = nzDIGIT *5DIGIT
27.5334 +
27.5335 +9.6. LIST Variants
27.5336 +
27.5337 + This section defines more specifically the keywords for the LIST
27.5338 + command and the syntax of the corresponding response contents.
27.5339 +
27.5340 + ; active
27.5341 + list-arguments =/ "ACTIVE" [WS wildmat]
27.5342 + list-content =/ list-active-content
27.5343 + list-active-content = active-groups-list
27.5344 +
27.5345 +
27.5346 + ; active.times
27.5347 + list-arguments =/ "ACTIVE.TIMES" [WS wildmat]
27.5348 + list-content =/ list-active-times-content
27.5349 + list-active-times-content =
27.5350 + *(newsgroup-name SPA 1*DIGIT SPA newsgroup-creator CRLF)
27.5351 + newsgroup-creator = U-TEXT
27.5352 +
27.5353 +
27.5354 + ; distrib.pats
27.5355 + list-arguments =/ "DISTRIB.PATS"
27.5356 + list-content =/ list-distrib-pats-content
27.5357 + list-distrib-pats-content =
27.5358 + *(1*DIGIT ":" wildmat ":" distribution CRLF)
27.5359 + distribution = token
27.5360 +
27.5361 +
27.5362 + ; headers
27.5363 + list-arguments =/ "HEADERS" [WS ("MSGID" / "RANGE")]
27.5364 + list-content =/ list-headers-content
27.5365 + list-headers-content = *(header-meta-name CRLF) /
27.5366 + *((metadata-name / ":") CRLF)
27.5367 +
27.5368 +
27.5369 + ; newsgroups
27.5370 + list-arguments =/ "NEWSGROUPS" [WS wildmat]
27.5371 + list-content =/ list-newsgroups-content
27.5372 + list-newsgroups-content =
27.5373 +
27.5374 +
27.5375 +
27.5376 +Feather Standards Track [Page 96]
27.5377 +
27.5378 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5379 +
27.5380 +
27.5381 + *(newsgroup-name WS newsgroup-description CRLF)
27.5382 + newsgroup-description = S-TEXT
27.5383 +
27.5384 +
27.5385 + ; overview.fmt
27.5386 + list-arguments =/ "OVERVIEW.FMT"
27.5387 + list-content =/ list-overview-fmt-content
27.5388 + list-overview-fmt-content = "Subject:" CRLF
27.5389 + "From:" CRLF
27.5390 + "Date:" CRLF
27.5391 + "Message-ID:" CRLF
27.5392 + "References:" CRLF
27.5393 + ( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF
27.5394 + *((header-name ":full" / metadata-name) CRLF)
27.5395 +
27.5396 +9.7. Articles
27.5397 +
27.5398 + This syntax defines the non-terminal <article>, which represents the
27.5399 + format of an article as described in Section 3.6.
27.5400 +
27.5401 + article = 1*header CRLF body
27.5402 + header = header-name ":" [CRLF] SP header-content CRLF
27.5403 + header-content = *(S-CHAR / [CRLF] WS)
27.5404 + body = *(*B-CHAR CRLF)
27.5405 +
27.5406 +9.8. General Non-terminals
27.5407 +
27.5408 + These non-terminals are used at various places in the syntax and are
27.5409 + collected here for convenience. A few of these non-terminals are not
27.5410 + used in this specification but are provided for the consistency and
27.5411 + convenience of extension authors.
27.5412 +
27.5413 + multi-line-data-block = content-lines termination
27.5414 + content-lines = *([content-text] CRLF)
27.5415 + content-text = (".." / B-NONDOT) *B-CHAR
27.5416 + termination = "." CRLF
27.5417 +
27.5418 + article-number = 1*16DIGIT
27.5419 + header-name = 1*A-NOTCOLON
27.5420 + keyword = ALPHA 2*(ALPHA / DIGIT / "." / "-")
27.5421 + message-id = "<" 1*248A-NOTGT ">"
27.5422 + newsgroup-name = 1*wildmat-exact
27.5423 + token = 1*P-CHAR
27.5424 +
27.5425 + wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
27.5426 + wildmat-pattern = 1*wildmat-item
27.5427 + wildmat-item = wildmat-exact / wildmat-wild
27.5428 + wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
27.5429 +
27.5430 +
27.5431 +
27.5432 +Feather Standards Track [Page 97]
27.5433 +
27.5434 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5435 +
27.5436 +
27.5437 + UTF8-non-ascii ; exclude ! * , ? [ \ ]
27.5438 + wildmat-wild = "*" / "?"
27.5439 +
27.5440 + base64 = *(4base64-char) [base64-terminal]
27.5441 + base64-char = UPPER / LOWER / DIGIT / "+" / "/"
27.5442 + base64-terminal = 2base64-char "==" / 3base64-char "="
27.5443 +
27.5444 + ; Assorted special character sets
27.5445 + ; A- means based on US-ASCII, excluding controls and SP
27.5446 + ; P- means based on UTF-8, excluding controls and SP
27.5447 + ; U- means based on UTF-8, excluding NUL CR and LF
27.5448 + ; B- means based on bytes, excluding NUL CR and LF
27.5449 + A-CHAR = %x21-7E
27.5450 + A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":"
27.5451 + A-NOTGT = %x21-3D / %x3F-7E ; exclude ">"
27.5452 + P-CHAR = A-CHAR / UTF8-non-ascii
27.5453 + U-CHAR = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii
27.5454 + U-NONTAB = CTRL / SP / A-CHAR / UTF8-non-ascii
27.5455 + U-TEXT = P-CHAR *U-CHAR
27.5456 + B-CHAR = CTRL / TAB / SP / %x21-FF
27.5457 + B-NONDOT = CTRL / TAB / SP / %x21-2D / %x2F-FF ; exclude "."
27.5458 +
27.5459 + ALPHA = UPPER / LOWER ; use only when case-insensitive
27.5460 + CR = %x0D
27.5461 + CRLF = CR LF
27.5462 + CTRL = %x01-08 / %x0B-0C / %x0E-1F
27.5463 + DIGIT = %x30-39
27.5464 + nzDIGIT = %x31-39
27.5465 + EOL = *(SP / TAB) CRLF
27.5466 + LF = %x0A
27.5467 + LOWER = %x61-7A
27.5468 + SP = %x20
27.5469 + SPA = 1*SP
27.5470 + TAB = %x09
27.5471 + UPPER = %x41-5A
27.5472 + UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4
27.5473 + UTF8-2 = %xC2-DF UTF8-tail
27.5474 + UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail /
27.5475 + %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail
27.5476 + UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail /
27.5477 + %xF4 %x80-8F 2UTF8-tail
27.5478 + UTF8-tail = %x80-BF
27.5479 + WS = 1*(SP / TAB)
27.5480 +
27.5481 + The following non-terminals require special consideration. They
27.5482 + represent situations where material SHOULD be restricted to UTF-8,
27.5483 + but implementations MUST be able to cope with other character
27.5484 + encodings. Therefore, there are two sets of definitions for them.
27.5485 +
27.5486 +
27.5487 +
27.5488 +Feather Standards Track [Page 98]
27.5489 +
27.5490 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5491 +
27.5492 +
27.5493 + Implementations MUST accept any content that meets this syntax:
27.5494 +
27.5495 + S-CHAR = %x21-FF
27.5496 + S-NONTAB = CTRL / SP / S-CHAR
27.5497 + S-TEXT = (CTRL / S-CHAR) *B-CHAR
27.5498 +
27.5499 + and MAY pass such content on unaltered.
27.5500 +
27.5501 + When generating new content or re-encoding existing content,
27.5502 + implementations SHOULD conform to this syntax:
27.5503 +
27.5504 + S-CHAR = P-CHAR
27.5505 + S-NONTAB = U-NONTAB
27.5506 + S-TEXT = U-TEXT
27.5507 +
27.5508 +9.9. Extensions and Validation
27.5509 +
27.5510 + The specification of a registered extension MUST include formal
27.5511 + syntax that defines additional forms for the following non-terminals:
27.5512 +
27.5513 + command
27.5514 + for each new command other than a variant of the LIST command -
27.5515 + the syntax of each command MUST be compatible with the definition
27.5516 + of <X-command>;
27.5517 +
27.5518 + command-datastream
27.5519 + for each new command that immediately streams data;
27.5520 +
27.5521 + command-continuation
27.5522 + for each new command that sends further material after the initial
27.5523 + command line - the syntax of each continuation MUST be exactly
27.5524 + what is sent to the server, including any escape mechanisms such
27.5525 + as "dot-stuffing";
27.5526 +
27.5527 + initial-response-content
27.5528 + for each new response code that has arguments - the syntax of each
27.5529 + response MUST be compatible with the definition of <X-initial-
27.5530 + response-content>;
27.5531 +
27.5532 + multi-line-response-content
27.5533 + for each new response code that has a multi-line response - the
27.5534 + syntax MUST show the response after the lines containing the
27.5535 + response code and the terminating octet have been removed and any
27.5536 + "dot-stuffing" undone;
27.5537 +
27.5538 + capability-entry
27.5539 + for each new capability label - the syntax of each entry MUST be
27.5540 + compatible with the definition of <X-capability-entry>;
27.5541 +
27.5542 +
27.5543 +
27.5544 +Feather Standards Track [Page 99]
27.5545 +
27.5546 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5547 +
27.5548 +
27.5549 + list-arguments
27.5550 + for each new variant of the LIST command - the syntax of each
27.5551 + entry MUST be compatible with the definition of <X-command>;
27.5552 +
27.5553 + list-content
27.5554 + for each new variant of the LIST command - the syntax MUST show
27.5555 + the response after the lines containing the 215 response code and
27.5556 + the terminating octet have been removed and any "dot-stuffing"
27.5557 + undone.
27.5558 +
27.5559 + The =/ notation of ABNF [RFC4234] and the naming conventions
27.5560 + described in Section 9.1 SHOULD be used for this.
27.5561 +
27.5562 + When the syntax in this specification, or syntax based on it, is
27.5563 + validated, it should be noted that:
27.5564 +
27.5565 + o the non-terminals <command-line>, <command-datastream>,
27.5566 + <command-continuation>, <response>, and
27.5567 + <multi-line-response-content> describe basic concepts of the
27.5568 + protocol and are not referred to by any other rule;
27.5569 +
27.5570 + o the non-terminal <base64> is provided for the convenience of
27.5571 + extension authors and is not referred to by any rule in this
27.5572 + specification;
27.5573 +
27.5574 + o for the reasons given above, the non-terminals <S-CHAR>,
27.5575 + <S-NONTAB>, and <S-TEXT> each have two definitions; and
27.5576 +
27.5577 + o the non-terminal <UNDEFINED> is deliberately not defined.
27.5578 +
27.5579 +10. Internationalisation Considerations
27.5580 +
27.5581 +10.1. Introduction and Historical Situation
27.5582 +
27.5583 + RFC 977 [RFC977] was written at a time when internationalisation was
27.5584 + not seen as a significant issue. As such, it was written on the
27.5585 + assumption that all communication would be in ASCII and use only a
27.5586 + 7-bit transport layer, although in practice just about all known
27.5587 + implementations are 8-bit clean.
27.5588 +
27.5589 + Since then, Usenet and NNTP have spread throughout the world. In the
27.5590 + absence of standards for handling the issues of language and
27.5591 + character sets, countries, newsgroup hierarchies, and individuals
27.5592 + have found a variety of solutions that work for them but that are not
27.5593 + necessarily appropriate elsewhere. For example, some have adopted a
27.5594 + default 8-bit character set appropriate to their needs (such as
27.5595 + ISO/IEC 8859-1 in Western Europe or KOI-8 in Russia), others have
27.5596 + used ASCII (either US-ASCII or national variants) in headers but
27.5597 +
27.5598 +
27.5599 +
27.5600 +Feather Standards Track [Page 100]
27.5601 +
27.5602 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5603 +
27.5604 +
27.5605 + local 16-bit character sets in article bodies, and still others have
27.5606 + gone for a combination of MIME [RFC2045] and UTF-8. With the
27.5607 + increased use of MIME in email, it is becoming more common to find
27.5608 + NNTP articles containing MIME headers that identify the character set
27.5609 + of the body, but this is far from universal.
27.5610 +
27.5611 + The resulting confusion does not help interoperability.
27.5612 +
27.5613 + One point that has been generally accepted is that articles can
27.5614 + contain octets with the top bit set, and NNTP is only expected to
27.5615 + operate on 8-bit clean transport paths.
27.5616 +
27.5617 +10.2. This Specification
27.5618 +
27.5619 + Part of the role of this present specification is to eliminate this
27.5620 + confusion and promote interoperability as far as possible. At the
27.5621 + same time, it is necessary to accept the existence of the present
27.5622 + situation and not break existing implementations and arrangements
27.5623 + gratuitously, even if they are less than optimal. Therefore, the
27.5624 + current practice described above has been taken into consideration in
27.5625 + producing this specification.
27.5626 +
27.5627 + This specification extends NNTP from US-ASCII [ANSI1986] to UTF-8
27.5628 + [RFC3629]. Except in the two areas discussed below, UTF-8 (which is
27.5629 + a superset of US-ASCII) is mandatory, and implementations MUST NOT
27.5630 + use any other encoding.
27.5631 +
27.5632 + Firstly, the use of MIME for article headers and bodies is strongly
27.5633 + recommended. However, given widely divergent existing practices, an
27.5634 + attempt to require a particular encoding and tagging standard would
27.5635 + be premature at this time. Accordingly, this specification allows
27.5636 + the use of arbitrary 8-bit data in articles subject to the following
27.5637 + requirements and recommendations.
27.5638 +
27.5639 + o The names of headers (e.g., "From" or "Subject") MUST be in
27.5640 + US-ASCII.
27.5641 +
27.5642 + o Header values SHOULD use US-ASCII or an encoding based on it, such
27.5643 + as RFC 2047 [RFC2047], until such time as another approach has
27.5644 + been standardised. At present, 8-bit encodings (including UTF-8)
27.5645 + SHOULD NOT be used because they are likely to cause
27.5646 + interoperability problems.
27.5647 +
27.5648 + o The character set of article bodies SHOULD be indicated in the
27.5649 + article headers, and this SHOULD be done in accordance with MIME.
27.5650 +
27.5651 + o Where an article is obtained from an external source, an
27.5652 + implementation MAY pass it on and derive data from it (such as the
27.5653 +
27.5654 +
27.5655 +
27.5656 +Feather Standards Track [Page 101]
27.5657 +
27.5658 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5659 +
27.5660 +
27.5661 + response to the HDR command), even though the article or the data
27.5662 + does not meet the above requirements. Implementations MUST
27.5663 + transfer such articles and data correctly and unchanged; they MUST
27.5664 + NOT attempt to convert or re-encode the article or derived data.
27.5665 + (Nevertheless, a client or server MAY elect not to post or forward
27.5666 + the article if, after further examination of the article, it deems
27.5667 + it inappropriate to do so.)
27.5668 +
27.5669 + This requirement affects the ARTICLE (Section 6.2.1), BODY
27.5670 + (Section 6.2.3), HDR (Section 8.5), HEAD (Section 6.2.2), IHAVE
27.5671 + (Section 6.3.2), OVER (Section 8.3), and POST (Section 6.3.1)
27.5672 + commands.
27.5673 +
27.5674 + Secondly, the following requirements are placed on the newsgroups
27.5675 + list returned by the LIST NEWSGROUPS command (Section 7.6.6):
27.5676 +
27.5677 + o Although this specification allows UTF-8 for newsgroup names, they
27.5678 + SHOULD be restricted to US-ASCII until a successor to RFC 1036
27.5679 + [RFC1036] standardises another approach. 8-bit encodings SHOULD
27.5680 + NOT be used because they are likely to cause interoperability
27.5681 + problems.
27.5682 +
27.5683 + o The newsgroup description SHOULD be in US-ASCII or UTF-8 unless
27.5684 + and until a successor to RFC 1036 standardises other encoding
27.5685 + arrangements. 8-bit encodings other than UTF-8 SHOULD NOT be used
27.5686 + because they are likely to cause interoperability problems.
27.5687 +
27.5688 + o Implementations that obtain this data from an external source MUST
27.5689 + handle it correctly even if it does not meet the above
27.5690 + requirements. Implementations (in particular, clients) MUST
27.5691 + handle such data correctly.
27.5692 +
27.5693 +10.3. Outstanding Issues
27.5694 +
27.5695 + While the primary use of NNTP is for transmitting articles that
27.5696 + conform to RFC 1036 (Netnews articles), it is also used for other
27.5697 + formats (see Appendix A). It is therefore most appropriate that
27.5698 + internationalisation issues related to article formats be addressed
27.5699 + in the relevant specifications. For Netnews articles, this is any
27.5700 + successor to RFC 1036. For email messages, it is RFC 2822 [RFC2822].
27.5701 +
27.5702 + Of course, any article transmitted via NNTP needs to conform to this
27.5703 + specification as well.
27.5704 +
27.5705 + Restricting newsgroup names to UTF-8 is not a complete solution. In
27.5706 + particular, when new newsgroup names are created or a user is asked
27.5707 + to enter a newsgroup name, some scheme of canonicalisation will need
27.5708 + to take place. This specification does not attempt to define that
27.5709 +
27.5710 +
27.5711 +
27.5712 +Feather Standards Track [Page 102]
27.5713 +
27.5714 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5715 +
27.5716 +
27.5717 + canonicalization; further work is needed in this area, in conjunction
27.5718 + with the article format specifications. Until such specifications
27.5719 + are published, implementations SHOULD match newsgroup names octet by
27.5720 + octet. It is anticipated that any approved scheme will be applied
27.5721 + "at the edges", and therefore octet-by-octet comparison will continue
27.5722 + to apply to most, if not all, uses of newsgroup names in NNTP.
27.5723 +
27.5724 + In the meantime, any implementation experimenting with UTF-8
27.5725 + newsgroup names is strongly cautioned that a future specification may
27.5726 + require that those names be canonicalized when used with NNTP in a
27.5727 + way that is not compatible with their experiments.
27.5728 +
27.5729 + Since the primary use of NNTP is with Netnews, and since newsgroup
27.5730 + descriptions are normally distributed through specially formatted
27.5731 + articles, it is recommended that the internationalisation issues
27.5732 + related to them be addressed in any successor to RFC 1036.
27.5733 +
27.5734 +11. IANA Considerations
27.5735 +
27.5736 + This specification requires IANA to keep a registry of capability
27.5737 + labels. The initial contents of this registry are specified in
27.5738 + Section 3.3.4. As described in Section 3.3.3, labels beginning with
27.5739 + X are reserved for private use, while all other names are expected to
27.5740 + be associated with a specification in an RFC on the standards track
27.5741 + or defining an IESG-approved experimental protocol.
27.5742 +
27.5743 + Different entries in the registry MUST use different capability
27.5744 + labels.
27.5745 +
27.5746 + Different entries in the registry MUST NOT use the same command name.
27.5747 + For this purpose, variants distinguished by a second or subsequent
27.5748 + keyword (e.g., "LIST HEADERS" and "LIST OVERVIEW.FMT") count as
27.5749 + different commands. If there is a need for two extensions to use the
27.5750 + same command, a single harmonised specification MUST be registered.
27.5751 +
27.5752 +12. Security Considerations
27.5753 +
27.5754 + This section is meant to inform application developers, information
27.5755 + providers, and users of the security limitations in NNTP as described
27.5756 + by this document. The discussion does not include definitive
27.5757 + solutions to the problems revealed, though it does make some
27.5758 + suggestions for reducing security risks.
27.5759 +
27.5760 +
27.5761 +
27.5762 +
27.5763 +
27.5764 +
27.5765 +
27.5766 +
27.5767 +
27.5768 +Feather Standards Track [Page 103]
27.5769 +
27.5770 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5771 +
27.5772 +
27.5773 +12.1. Personal and Proprietary Information
27.5774 +
27.5775 + NNTP, because it was created to distribute network news articles,
27.5776 + will forward whatever information is stored in those articles.
27.5777 + Specification of that information is outside this scope of this
27.5778 + document, but it is likely that some personal and/or proprietary
27.5779 + information is available in some of those articles. It is very
27.5780 + important that designers and implementers provide informative
27.5781 + warnings to users so that personal and/or proprietary information in
27.5782 + material that is added automatically to articles (e.g., in headers)
27.5783 + is not disclosed inadvertently. Additionally, effective and easily
27.5784 + understood mechanisms to manage the distribution of news articles
27.5785 + SHOULD be provided to NNTP Server administrators, so that they are
27.5786 + able to report with confidence the likely spread of any particular
27.5787 + set of news articles.
27.5788 +
27.5789 +12.2. Abuse of Server Log Information
27.5790 +
27.5791 + A server is in the position to save session data about a user's
27.5792 + requests that might identify their reading patterns or subjects of
27.5793 + interest. This information is clearly confidential in nature, and
27.5794 + its handling can be constrained by law in certain countries. People
27.5795 + using this protocol to provide data are responsible for ensuring that
27.5796 + such material is not distributed without the permission of any
27.5797 + individuals that are identifiable by the published results.
27.5798 +
27.5799 +12.3. Weak Authentication and Access Control
27.5800 +
27.5801 + There is no user-based or token-based authentication in the basic
27.5802 + NNTP specification. Access is normally controlled by server
27.5803 + configuration files. Those files specify access by using domain
27.5804 + names or IP addresses. However, this specification does permit the
27.5805 + creation of extensions to NNTP for such purposes; one such extension
27.5806 + is [NNTP-AUTH]. While including such mechanisms is optional, doing
27.5807 + so is strongly encouraged.
27.5808 +
27.5809 + Other mechanisms are also available. For example, a proxy server
27.5810 + could be put in place that requires authentication before connecting
27.5811 + via the proxy to the NNTP server.
27.5812 +
27.5813 +12.4. DNS Spoofing
27.5814 +
27.5815 + Many existing NNTP implementations authorize incoming connections by
27.5816 + checking the IP address of that connection against the IP addresses
27.5817 + obtained via DNS lookups of lists of domain names given in local
27.5818 + configuration files. Servers that use this type of authentication
27.5819 + and clients that find a server by doing a DNS lookup of the server
27.5820 + name rely very heavily on the Domain Name Service, and are thus
27.5821 +
27.5822 +
27.5823 +
27.5824 +Feather Standards Track [Page 104]
27.5825 +
27.5826 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5827 +
27.5828 +
27.5829 + generally prone to security attacks based on the deliberate
27.5830 + misassociation of IP addresses and DNS names. Clients and servers
27.5831 + need to be cautious in assuming the continuing validity of an IP
27.5832 + number/DNS name association.
27.5833 +
27.5834 + In particular, NNTP clients and servers SHOULD rely on their name
27.5835 + resolver for confirmation of an IP number/DNS name association,
27.5836 + rather than cache the result of previous host name lookups. Many
27.5837 + platforms already can cache host name lookups locally when
27.5838 + appropriate, and they SHOULD be configured to do so. It is proper
27.5839 + for these lookups to be cached, however, only when the TTL (Time To
27.5840 + Live) information reported by the name server makes it likely that
27.5841 + the cached information will remain useful.
27.5842 +
27.5843 + If NNTP clients or servers cache the results of host name lookups in
27.5844 + order to achieve a performance improvement, they MUST observe the TTL
27.5845 + information reported by DNS. If NNTP clients or servers do not
27.5846 + observe this rule, they could be spoofed when a previously accessed
27.5847 + server's IP address changes. As network renumbering is expected to
27.5848 + become increasingly common, the possibility of this form of attack
27.5849 + will increase. Observing this requirement thus reduces this
27.5850 + potential security vulnerability.
27.5851 +
27.5852 + This requirement also improves the load-balancing behaviour of
27.5853 + clients for replicated servers using the same DNS name and reduces
27.5854 + the likelihood of a user's experiencing failure in accessing sites
27.5855 + that use that strategy.
27.5856 +
27.5857 +12.5. UTF-8 Issues
27.5858 +
27.5859 + UTF-8 [RFC3629] permits only certain sequences of octets and
27.5860 + designates others as either malformed or "illegal". The Unicode
27.5861 + standard identifies a number of security issues related to illegal
27.5862 + sequences and forbids their generation by conforming implementations.
27.5863 +
27.5864 + Implementations of this specification MUST NOT generate malformed or
27.5865 + illegal sequences and SHOULD detect them and take some appropriate
27.5866 + action. This could include the following:
27.5867 +
27.5868 + o Generating a 501 response code.
27.5869 +
27.5870 + o Replacing such sequences by the sequence %xEF.BF.BD, which encodes
27.5871 + the "replacement character" U+FFFD.
27.5872 +
27.5873 + o Closing the connection.
27.5874 +
27.5875 + o Replacing such sequences by a "guessed" valid sequence (based on
27.5876 + properties of the UTF-8 encoding).
27.5877 +
27.5878 +
27.5879 +
27.5880 +Feather Standards Track [Page 105]
27.5881 +
27.5882 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5883 +
27.5884 +
27.5885 + In the last case, the implementation MUST ensure that any replacement
27.5886 + cannot be used to bypass validity or security checks. For example,
27.5887 + the illegal sequence %xC0.A0 is an over-long encoding for space
27.5888 + (%x20). If it is replaced by the correct encoding in a command line,
27.5889 + this needs to happen before the command line is parsed into
27.5890 + individual arguments. If the replacement came after parsing, it
27.5891 + would be possible to generate an argument with an embedded space,
27.5892 + which is forbidden. Use of the "replacement character" does not have
27.5893 + this problem, since it is permitted wherever non-US-ASCII characters
27.5894 + are. Implementations SHOULD use one of the first two solutions where
27.5895 + the general structure of the NNTP stream remains intact and SHOULD
27.5896 + close the connection if it is no longer possible to parse it
27.5897 + sensibly.
27.5898 +
27.5899 +12.6. Caching of Capability Lists
27.5900 +
27.5901 + The CAPABILITIES command provides a capability list, which is
27.5902 + information about the current capabilities of the server. Whenever
27.5903 + there is a relevant change to the server state, the results of this
27.5904 + command are required to change accordingly.
27.5905 +
27.5906 + In most situations, the capabilities list in a given server state
27.5907 + will not change from session to session; for example, a given
27.5908 + extension will be installed permanently on a server. Some clients
27.5909 + may therefore wish to remember which extensions a server supports to
27.5910 + avoid the delay of an additional command and response, particularly
27.5911 + if they open multiple connections in the same session.
27.5912 +
27.5913 + However, information about extensions related to security and privacy
27.5914 + MUST NOT be cached, since this could allow a variety of attacks.
27.5915 +
27.5916 + For example, consider a server that permits the use of cleartext
27.5917 + passwords on links that are encrypted but not otherwise:
27.5918 +
27.5919 + [Initial connection set-up completed.]
27.5920 + [S] 200 NNTP Service Ready, posting permitted
27.5921 + [C] CAPABILITIES
27.5922 + [S] 101 Capability list:
27.5923 + [S] VERSION 2
27.5924 + [S] READER
27.5925 + [S] NEWNEWS
27.5926 + [S] POST
27.5927 + [S] XENCRYPT
27.5928 + [S] LIST ACTIVE NEWSGROUPS
27.5929 + [S] .
27.5930 + [C] XENCRYPT
27.5931 + [Client and server negotiate encryption on the link]
27.5932 + [S] 283 Encrypted link established
27.5933 +
27.5934 +
27.5935 +
27.5936 +Feather Standards Track [Page 106]
27.5937 +
27.5938 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5939 +
27.5940 +
27.5941 + [C] CAPABILITIES
27.5942 + [S] 101 Capability list:
27.5943 + [S] VERSION 2
27.5944 + [S] READER
27.5945 + [S] NEWNEWS
27.5946 + [S] POST
27.5947 + [S] XSECRET
27.5948 + [S] LIST ACTIVE NEWSGROUPS
27.5949 + [S] .
27.5950 + [C] XSECRET fred flintstone
27.5951 + [S] 290 Password for fred accepted
27.5952 +
27.5953 + If the client caches the last capabilities list, then on the next
27.5954 + session it will attempt to use XSECRET on an unencrypted link:
27.5955 +
27.5956 + [Initial connection set-up completed.]
27.5957 + [S] 200 NNTP Service Ready, posting permitted
27.5958 + [C] XSECRET fred flintstone
27.5959 + [S] 483 Only permitted on secure links
27.5960 +
27.5961 + This exposes the password to any eavesdropper. While the primary
27.5962 + cause of this is passing a secret without first checking the security
27.5963 + of the link, caching of capability lists can increase the risk.
27.5964 +
27.5965 + Any security extension should include requirements to check the
27.5966 + security state of the link in a manner appropriate to that extension.
27.5967 +
27.5968 + Caching should normally only be considered for anonymous clients that
27.5969 + do not use any security or privacy extensions and for which the time
27.5970 + required for an additional command and response is a noticeable
27.5971 + issue.
27.5972 +
27.5973 +13. Acknowledgements
27.5974 +
27.5975 + This document is the result of much effort by the present and past
27.5976 + members of the NNTP Working Group, chaired by Russ Allbery and Ned
27.5977 + Freed. It could not have been produced without them.
27.5978 +
27.5979 + The author acknowledges the original authors of NNTP as documented in
27.5980 + RFC 977 [RFC977]: Brian Kantor and Phil Lapsey.
27.5981 +
27.5982 + The author gratefully acknowledges the following:
27.5983 +
27.5984 + o The work of the NNTP committee chaired by Eliot Lear. The
27.5985 + organization of this document was influenced by the last available
27.5986 + version from this working group. A special thanks to Eliot for
27.5987 + generously providing the original machine-readable sources for
27.5988 + that document.
27.5989 +
27.5990 +
27.5991 +
27.5992 +Feather Standards Track [Page 107]
27.5993 +
27.5994 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.5995 +
27.5996 +
27.5997 + o The work of the DRUMS working group, specifically RFC 1869
27.5998 + [RFC1869], that drove the original thinking that led to the
27.5999 + CAPABILITIES command and the extensions mechanism detailed in this
27.6000 + document.
27.6001 +
27.6002 + o The authors of RFC 2616 [RFC2616] for providing specific and
27.6003 + relevant examples of security issues that should be considered for
27.6004 + HTTP. Since many of the same considerations exist for NNTP, those
27.6005 + examples that are relevant have been included here with some minor
27.6006 + rewrites.
27.6007 +
27.6008 + o The comments and additional information provided by the following
27.6009 + individuals in preparing one or more of the progenitors of this
27.6010 + document:
27.6011 +
27.6012 + Russ Allbery <rra@stanford.edu>
27.6013 + Wayne Davison <davison@armory.com>
27.6014 + Chris Lewis <clewis@bnr.ca>
27.6015 + Tom Limoncelli <tal@mars.superlink.net>
27.6016 + Eric Schnoebelen <eric@egsner.cirr.com>
27.6017 + Rich Salz <rsalz@osf.org>
27.6018 +
27.6019 + This work was motivated by the work of various news reader authors
27.6020 + and news server authors, including those listed below:
27.6021 +
27.6022 + Rick Adams
27.6023 + Original author of the NNTP extensions to the RN news reader and
27.6024 + last maintainer of Bnews.
27.6025 +
27.6026 + Stan Barber
27.6027 + Original author of the NNTP extensions to the news readers that
27.6028 + are part of Bnews.
27.6029 +
27.6030 + Geoff Collyer
27.6031 + Original author of the OVERVIEW database proposal and one of the
27.6032 + original authors of CNEWS.
27.6033 +
27.6034 + Dan Curry
27.6035 + Original author of the xvnews news reader.
27.6036 +
27.6037 + Wayne Davison
27.6038 + Author of the first threading extensions to the RN news reader
27.6039 + (commonly called TRN).
27.6040 +
27.6041 + Geoff Huston
27.6042 + Original author of ANU NEWS.
27.6043 +
27.6044 +
27.6045 +
27.6046 +
27.6047 +
27.6048 +Feather Standards Track [Page 108]
27.6049 +
27.6050 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6051 +
27.6052 +
27.6053 + Phil Lapsey
27.6054 + Original author of the UNIX reference implementation for NNTP.
27.6055 +
27.6056 + Iain Lea
27.6057 + Original maintainer of the TIN news reader.
27.6058 +
27.6059 + Chris Lewis
27.6060 + First known implementer of the AUTHINFO GENERIC extension.
27.6061 +
27.6062 + Rich Salz
27.6063 + Original author of INN.
27.6064 +
27.6065 + Henry Spencer
27.6066 + One of the original authors of CNEWS.
27.6067 +
27.6068 + Kim Storm
27.6069 + Original author of the NN news reader.
27.6070 +
27.6071 + Other people who contributed to this document include:
27.6072 +
27.6073 + Matthias Andree
27.6074 + Greg Andruk
27.6075 + Daniel Barclay
27.6076 + Maurizio Codogno
27.6077 + Mark Crispin
27.6078 + Andrew Gierth
27.6079 + Juergen Helbing
27.6080 + Scott Hollenbeck
27.6081 + Urs Janssen
27.6082 + Charles Lindsey
27.6083 + Ade Lovett
27.6084 + David Magda
27.6085 + Ken Murchison
27.6086 + Francois Petillon
27.6087 + Peter Robinson
27.6088 + Rob Siemborski
27.6089 + Howard Swinehart
27.6090 + Ruud van Tol
27.6091 + Jeffrey Vinocur
27.6092 + Erik Warmelink
27.6093 +
27.6094 + The author thanks them all and apologises to anyone omitted.
27.6095 +
27.6096 + Finally, the present author gratefully acknowledges the vast amount
27.6097 + of work put into previous versions by the previous author:
27.6098 +
27.6099 + Stan Barber <sob@academ.com>
27.6100 +
27.6101 +
27.6102 +
27.6103 +
27.6104 +Feather Standards Track [Page 109]
27.6105 +
27.6106 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6107 +
27.6108 +
27.6109 +14. References
27.6110 +
27.6111 +14.1. Normative References
27.6112 +
27.6113 + [ANSI1986] American National Standards Institute, "Coded Character
27.6114 + Set - 7-bit American Standard Code for Information
27.6115 + Interchange", ANSI X3.4, 1986.
27.6116 +
27.6117 + [RFC977] Kantor, B. and P. Lapsley, "Network News Transfer
27.6118 + Protocol", RFC 977, February 1986.
27.6119 +
27.6120 + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet
27.6121 + Mail Extensions (MIME) Part One: Format of Internet
27.6122 + Message Bodies", RFC 2045, November 1996.
27.6123 +
27.6124 + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail
27.6125 + Extensions) Part Three: Message Header Extensions for
27.6126 + Non-ASCII Text", RFC 2047, November 1996.
27.6127 +
27.6128 + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
27.6129 + Requirement Levels", BCP 14, RFC 2119, March 1997.
27.6130 +
27.6131 + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
27.6132 + 10646", STD 63, RFC 3629, November 2003.
27.6133 +
27.6134 + [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for
27.6135 + Syntax Specifications: ABNF", RFC 4234, October 2005.
27.6136 +
27.6137 + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
27.6138 + Encodings", RFC 4648, October 2006.
27.6139 +
27.6140 + [TF.686-1] International Telecommunications Union - Radio,
27.6141 + "Glossary, ITU-R Recommendation TF.686-1",
27.6142 + ITU-R Recommendation TF.686-1, October 1997.
27.6143 +
27.6144 +14.2. Informative References
27.6145 +
27.6146 + [NNTP-AUTH] Vinocur, J., Murchison, K., and C. Newman, "Network
27.6147 + News Transfer Protocol (NNTP) Extension for
27.6148 + Authentication",
27.6149 + RFC 4643, October 2006.
27.6150 +
27.6151 + [NNTP-STREAM] Vinocur, J. and K. Murchison, "Network News Transfer
27.6152 + Protocol (NNTP) Extension for Streaming Feeds",
27.6153 + RFC 4644, October 2006.
27.6154 +
27.6155 +
27.6156 +
27.6157 +
27.6158 +
27.6159 +
27.6160 +Feather Standards Track [Page 110]
27.6161 +
27.6162 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6163 +
27.6164 +
27.6165 + [NNTP-TLS] Murchison, K., Vinocur, J., and C. Newman, "Using
27.6166 + Transport Layer Security (TLS) with Network News
27.6167 + Transfer Protocol (NNTP)", RFC 4642, October 2006.
27.6168 +
27.6169 + [RFC1036] Horton, M. and R. Adams, "Standard for interchange of
27.6170 + USENET messages", RFC 1036, December 1987.
27.6171 +
27.6172 + [RFC1305] Mills, D., "Network Time Protocol (Version 3)
27.6173 + Specification, Implementation and Analysis", RFC 1305,
27.6174 + March 1992.
27.6175 +
27.6176 + [RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D.
27.6177 + Crocker, "SMTP Service Extensions", STD 10, RFC 1869,
27.6178 + November 1995.
27.6179 +
27.6180 + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
27.6181 + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
27.6182 + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
27.6183 +
27.6184 + [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
27.6185 + June 1999.
27.6186 +
27.6187 + [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April
27.6188 + 2001.
27.6189 +
27.6190 + [RFC2980] Barber, S., "Common NNTP Extensions", RFC 2980, October
27.6191 + 2000.
27.6192 +
27.6193 + [ROBE1995] Robertson, R., "FAQ: Overview database / NOV General
27.6194 + Information", January 1995.
27.6195 +
27.6196 + There is no definitive copy of this document known to
27.6197 + the author. It was previously posted as the Usenet
27.6198 + article <news:nov-faq-1-930909720@agate.Berkeley.EDU>
27.6199 +
27.6200 + [SALZ1992] Salz, R., "Manual Page for wildmat(3) from the INN 1.4
27.6201 + distribution, Revision 1.10", April 1992.
27.6202 +
27.6203 + There is no definitive copy of this document known to
27.6204 + the author.
27.6205 +
27.6206 +
27.6207 +
27.6208 +
27.6209 +
27.6210 +
27.6211 +
27.6212 +
27.6213 +
27.6214 +
27.6215 +
27.6216 +Feather Standards Track [Page 111]
27.6217 +
27.6218 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6219 +
27.6220 +
27.6221 +Appendix A. Interaction with Other Specifications
27.6222 +
27.6223 + NNTP is most often used for transferring articles that conform to
27.6224 + RFC 1036 [RFC1036] (such articles are called "Netnews articles"
27.6225 + here). It is also sometimes used for transferring email messages
27.6226 + that conform to RFC 2822 [RFC2822] (such articles are called "email
27.6227 + articles" here). In this situation, articles must conform both to
27.6228 + this specification and to that other one; this appendix describes
27.6229 + some relevant issues.
27.6230 +
27.6231 +A.1. Header Folding
27.6232 +
27.6233 + NNTP allows a header line to be folded (by inserting a CRLF pair)
27.6234 + before any space or TAB character.
27.6235 +
27.6236 + Both email and Netnews articles are required to have at least one
27.6237 + octet other than space or TAB on each header line. Thus, folding can
27.6238 + only happen at one point in each sequence of consecutive spaces or
27.6239 + TABs. Netnews articles are further required to have the header name,
27.6240 + colon, and following space all on the first line; folding may only
27.6241 + happen beyond that space. Finally, some non-conforming software will
27.6242 + remove trailing spaces and TABs from a line. Therefore, it might be
27.6243 + inadvisable to fold a header after a space or TAB.
27.6244 +
27.6245 + For maximum safety, header lines SHOULD conform to the following
27.6246 + syntax rather than to that in Section 9.7.
27.6247 +
27.6248 +
27.6249 + header = header-name ":" SP [header-content] CRLF
27.6250 + header-content = [WS] token *( [CRLF] WS token )
27.6251 +
27.6252 +A.2. Message-IDs
27.6253 +
27.6254 + Every article handled by an NNTP server MUST have a unique
27.6255 + message-id. For the purposes of this specification, a message-id is
27.6256 + an arbitrary opaque string that merely needs to meet certain
27.6257 + syntactic requirements and is just a way to refer to the article.
27.6258 +
27.6259 + Because there is a significant risk that old articles will be
27.6260 + reinjected into the global Usenet system, RFC 1036 [RFC1036] requires
27.6261 + that message-ids are globally unique for all time.
27.6262 +
27.6263 + This specification states that message-ids are the same if and only
27.6264 + if they consist of the same sequence of octets. Other specifications
27.6265 + may define two different sequences as being equal because they are
27.6266 + putting an interpretation on particular characters. RFC 2822
27.6267 + [RFC2822] has a concept of "quoted" and "escaped" characters. It
27.6268 + therefore considers the three message-ids:
27.6269 +
27.6270 +
27.6271 +
27.6272 +Feather Standards Track [Page 112]
27.6273 +
27.6274 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6275 +
27.6276 +
27.6277 + <ab.cd@example.com>
27.6278 + <"ab.cd"@example.com>
27.6279 + <"ab.\cd"@example.com>
27.6280 +
27.6281 + as being identical. Therefore, an NNTP implementation handing email
27.6282 + articles must ensure that only one of these three appears in the
27.6283 + protocol and that the other two are converted to it as and when
27.6284 + necessary, such as when a client checks the results of a NEWNEWS
27.6285 + command against an internal database of message-ids. Note that
27.6286 + RFC 1036 [RFC1036] never treats two different strings as being
27.6287 + identical. Its successor (as of the time of writing) restricts the
27.6288 + syntax of message-ids so that, whenever RFC 2822 would treat two
27.6289 + strings as equivalent, only one of them is valid (in the above
27.6290 + example, only the first string is valid).
27.6291 +
27.6292 + This specification does not describe how the message-id of an article
27.6293 + is determined; it may be deduced from the contents of the article or
27.6294 + derived from some external source. If the server is also conforming
27.6295 + to another specification that contains a definition of message-id
27.6296 + compatible with this one, the server SHOULD use those message-ids. A
27.6297 + common approach, and one that SHOULD be used for email and Netnews
27.6298 + articles, is to extract the message-id from the contents of a header
27.6299 + with name "Message-ID". This may not be as simple as copying the
27.6300 + entire header contents; it may be necessary to strip off comments and
27.6301 + undo quoting, or to reduce "equivalent" message-ids to a canonical
27.6302 + form.
27.6303 +
27.6304 + If an article is obtained through the IHAVE command, there will be a
27.6305 + message-id provided with the command. The server MAY either use it
27.6306 + or determine one from the article contents. However, whichever it
27.6307 + does, it SHOULD ensure that, if the IHAVE command is repeated with
27.6308 + the same argument and article, it will be recognized as a duplicate.
27.6309 +
27.6310 + If an article does not contain a message-id that the server can
27.6311 + identify, it MUST synthesize one. This could, for example, be a
27.6312 + simple sequence number or be based on the date and time when the
27.6313 + article arrived. When email or Netnews articles are handled, a
27.6314 + Message-ID header SHOULD be added to ensure global consistency and
27.6315 + uniqueness.
27.6316 +
27.6317 + Note that, because the message-id might not have been derived from
27.6318 + the Message-ID header in the article, the following example is
27.6319 + legitimate (though unusual):
27.6320 +
27.6321 +
27.6322 +
27.6323 +
27.6324 +
27.6325 +
27.6326 +
27.6327 +
27.6328 +Feather Standards Track [Page 113]
27.6329 +
27.6330 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6331 +
27.6332 +
27.6333 + [C] HEAD <45223423@example.com>
27.6334 + [S] 221 0 <45223423@example.com>
27.6335 + [S] Path: pathost!demo!whitehouse!not-for-mail
27.6336 + [S] Message-ID: <1234@example.net>
27.6337 + [S] From: "Demo User" <nobody@example.net>
27.6338 + [S] Newsgroups: misc.test
27.6339 + [S] Subject: I am just a test article
27.6340 + [S] Date: 6 Oct 1998 04:38:40 -0500
27.6341 + [S] Organization: An Example Net, Uncertain, Texas
27.6342 + [S] .
27.6343 +
27.6344 +A.3. Article Posting
27.6345 +
27.6346 + As far as NNTP is concerned, the POST and IHAVE commands provide the
27.6347 + same basic facilities in a slightly different way. However, they
27.6348 + have rather different intentions.
27.6349 +
27.6350 + The IHAVE command is intended for transmitting conforming articles
27.6351 + between a system of NNTP servers, with all articles perhaps also
27.6352 + conforming to another specification (e.g., all articles are Netnews
27.6353 + articles). It is expected that the client will already have done any
27.6354 + necessary validation (or that it has in turn obtained the article
27.6355 + from a third party that has done so); therefore, the contents SHOULD
27.6356 + be left unchanged.
27.6357 +
27.6358 + In contrast, the POST command is intended for use when an end-user is
27.6359 + injecting a newly created article into a such a system. The article
27.6360 + being transferred might not be a conforming email or Netnews article,
27.6361 + and the server is expected to validate it and, if necessary, to
27.6362 + convert it to the right form for onward distribution. This is often
27.6363 + done by a separate piece of software on the server installation; if
27.6364 + so, the NNTP server SHOULD pass the incoming article to that software
27.6365 + unaltered, making no attempt to filter characters, to fold or limit
27.6366 + lines, or to process the incoming text otherwise.
27.6367 +
27.6368 + The POST command can fail in various ways, and clients should be
27.6369 + prepared to re-send an article. When doing so, however, it is often
27.6370 + important to ensure (as far as possible) that the same message-id is
27.6371 + allocated to both attempts so that the server, or other servers, can
27.6372 + recognize the two articles as duplicates. In the case of email or
27.6373 + Netnews articles, therefore, the posted article SHOULD contain a
27.6374 + header with the name "Message-ID", and the contents of this header
27.6375 + SHOULD be identical on each attempt. The server SHOULD ensure that
27.6376 + two POSTed articles with the same contents for this header are
27.6377 + recognized as identical and that the same message-id is allocated,
27.6378 + whether or not those contents are suitable for use as the message-id.
27.6379 +
27.6380 +
27.6381 +
27.6382 +
27.6383 +
27.6384 +Feather Standards Track [Page 114]
27.6385 +
27.6386 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6387 +
27.6388 +
27.6389 +Appendix B. Summary of Commands
27.6390 +
27.6391 + This section contains a list of every command defined in this
27.6392 + document, ordered by command name and by indicating capability.
27.6393 +
27.6394 + Ordered by command name:
27.6395 +
27.6396 + +-------------------+-----------------------+---------------+
27.6397 + | Command | Indicating capability | Definition |
27.6398 + +-------------------+-----------------------+---------------+
27.6399 + | ARTICLE | READER | Section 6.2.1 |
27.6400 + | BODY | READER | Section 6.2.3 |
27.6401 + | CAPABILITIES | mandatory | Section 5.2 |
27.6402 + | DATE | READER | Section 7.1 |
27.6403 + | GROUP | READER | Section 6.1.1 |
27.6404 + | HDR | HDR | Section 8.5 |
27.6405 + | HEAD | mandatory | Section 6.2.2 |
27.6406 + | HELP | mandatory | Section 7.2 |
27.6407 + | IHAVE | IHAVE | Section 6.3.2 |
27.6408 + | LAST | READER | Section 6.1.3 |
27.6409 + | LIST | LIST | Section 7.6.1 |
27.6410 + | LIST ACTIVE.TIMES | LIST | Section 7.6.4 |
27.6411 + | LIST ACTIVE | LIST | Section 7.6.3 |
27.6412 + | LIST DISTRIB.PATS | LIST | Section 7.6.5 |
27.6413 + | LIST HEADERS | HDR | Section 8.6 |
27.6414 + | LIST NEWSGROUPS | LIST | Section 7.6.6 |
27.6415 + | LIST OVERVIEW.FMT | OVER | Section 8.4 |
27.6416 + | LISTGROUP | READER | Section 6.1.2 |
27.6417 + | MODE READER | MODE-READER | Section 5.3 |
27.6418 + | NEWGROUPS | READER | Section 7.3 |
27.6419 + | NEWNEWS | NEWNEWS | Section 7.4 |
27.6420 + | NEXT | READER | Section 6.1.4 |
27.6421 + | OVER | OVER | Section 8.3 |
27.6422 + | POST | POST | Section 6.3.1 |
27.6423 + | QUIT | mandatory | Section 5.4 |
27.6424 + | STAT | mandatory | Section 6.2.4 |
27.6425 + +-------------------+-----------------------+---------------+
27.6426 +
27.6427 +
27.6428 +
27.6429 +
27.6430 +
27.6431 +
27.6432 +
27.6433 +
27.6434 +
27.6435 +
27.6436 +
27.6437 +
27.6438 +
27.6439 +
27.6440 +Feather Standards Track [Page 115]
27.6441 +
27.6442 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6443 +
27.6444 +
27.6445 + Ordered by indicating capability:
27.6446 +
27.6447 + +-------------------+-----------------------+---------------+
27.6448 + | Command | Indicating capability | Definition |
27.6449 + +-------------------+-----------------------+---------------+
27.6450 + | CAPABILITIES | mandatory | Section 5.2 |
27.6451 + | HEAD | mandatory | Section 6.2.2 |
27.6452 + | HELP | mandatory | Section 7.2 |
27.6453 + | QUIT | mandatory | Section 5.4 |
27.6454 + | STAT | mandatory | Section 6.2.4 |
27.6455 + | HDR | HDR | Section 8.5 |
27.6456 + | LIST HEADERS | HDR | Section 8.6 |
27.6457 + | IHAVE | IHAVE | Section 6.3.2 |
27.6458 + | LIST | LIST | Section 7.6.1 |
27.6459 + | LIST ACTIVE | LIST | Section 7.6.3 |
27.6460 + | LIST ACTIVE.TIMES | LIST | Section 7.6.4 |
27.6461 + | LIST DISTRIB.PATS | LIST | Section 7.6.5 |
27.6462 + | LIST NEWSGROUPS | LIST | Section 7.6.6 |
27.6463 + | MODE READER | MODE-READER | Section 5.3 |
27.6464 + | NEWNEWS | NEWNEWS | Section 7.4 |
27.6465 + | OVER | OVER | Section 8.3 |
27.6466 + | LIST OVERVIEW.FMT | OVER | Section 8.4 |
27.6467 + | POST | POST | Section 6.3.1 |
27.6468 + | ARTICLE | READER | Section 6.2.1 |
27.6469 + | BODY | READER | Section 6.2.3 |
27.6470 + | DATE | READER | Section 7.1 |
27.6471 + | GROUP | READER | Section 6.1.1 |
27.6472 + | LAST | READER | Section 6.1.3 |
27.6473 + | LISTGROUP | READER | Section 6.1.2 |
27.6474 + | NEWGROUPS | READER | Section 7.3 |
27.6475 + | NEXT | READER | Section 6.1.4 |
27.6476 + +-------------------+-----------------------+---------------+
27.6477 +
27.6478 +
27.6479 +
27.6480 +
27.6481 +
27.6482 +
27.6483 +
27.6484 +
27.6485 +
27.6486 +
27.6487 +
27.6488 +
27.6489 +
27.6490 +
27.6491 +
27.6492 +
27.6493 +
27.6494 +
27.6495 +
27.6496 +Feather Standards Track [Page 116]
27.6497 +
27.6498 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6499 +
27.6500 +
27.6501 +Appendix C. Summary of Response Codes
27.6502 +
27.6503 + This section contains a list of every response code defined in this
27.6504 + document and indicates whether it is multi-line, which commands can
27.6505 + generate it, what arguments it has, and what its meaning is.
27.6506 +
27.6507 + Response code 100 (multi-line)
27.6508 + Generated by: HELP
27.6509 + Meaning: help text follows.
27.6510 +
27.6511 + Response code 101 (multi-line)
27.6512 + Generated by: CAPABILITIES
27.6513 + Meaning: capabilities list follows.
27.6514 +
27.6515 + Response code 111
27.6516 + Generated by: DATE
27.6517 + 1 argument: yyyymmddhhmmss
27.6518 + Meaning: server date and time.
27.6519 +
27.6520 + Response code 200
27.6521 + Generated by: initial connection, MODE READER
27.6522 + Meaning: service available, posting allowed.
27.6523 +
27.6524 + Response code 201
27.6525 + Generated by: initial connection, MODE READER
27.6526 + Meaning: service available, posting prohibited.
27.6527 +
27.6528 + Response code 205
27.6529 + Generated by: QUIT
27.6530 + Meaning: connection closing (the server immediately closes the
27.6531 + connection).
27.6532 +
27.6533 + Response code 211
27.6534 + The 211 response code has two completely different forms,
27.6535 + depending on which command generated it:
27.6536 +
27.6537 + (not multi-line)
27.6538 + Generated by: GROUP
27.6539 + 4 arguments: number low high group
27.6540 + Meaning: group selected.
27.6541 +
27.6542 + (multi-line)
27.6543 + Generated by: LISTGROUP
27.6544 + 4 arguments: number low high group
27.6545 + Meaning: article numbers follow.
27.6546 +
27.6547 +
27.6548 +
27.6549 +
27.6550 +
27.6551 +
27.6552 +Feather Standards Track [Page 117]
27.6553 +
27.6554 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6555 +
27.6556 +
27.6557 + Response code 215 (multi-line)
27.6558 + Generated by: LIST
27.6559 + Meaning: information follows.
27.6560 +
27.6561 + Response code 220 (multi-line)
27.6562 + Generated by: ARTICLE
27.6563 + 2 arguments: n message-id
27.6564 + Meaning: article follows.
27.6565 +
27.6566 + Response code 221 (multi-line)
27.6567 + Generated by: HEAD
27.6568 + 2 arguments: n message-id
27.6569 + Meaning: article headers follow.
27.6570 +
27.6571 + Response code 222 (multi-line)
27.6572 + Generated by: BODY
27.6573 + 2 arguments: n message-id
27.6574 + Meaning: article body follows.
27.6575 +
27.6576 + Response code 223
27.6577 + Generated by: LAST, NEXT, STAT
27.6578 + 2 arguments: n message-id
27.6579 + Meaning: article exists and selected.
27.6580 +
27.6581 + Response code 224 (multi-line)
27.6582 + Generated by: OVER
27.6583 + Meaning: overview information follows.
27.6584 +
27.6585 + Response code 225 (multi-line)
27.6586 + Generated by: HDR
27.6587 + Meaning: headers follow.
27.6588 +
27.6589 + Response code 230 (multi-line)
27.6590 + Generated by: NEWNEWS
27.6591 + Meaning: list of new articles follows.
27.6592 +
27.6593 + Response code 231 (multi-line)
27.6594 + Generated by: NEWGROUPS
27.6595 + Meaning: list of new newsgroups follows.
27.6596 +
27.6597 + Response code 235
27.6598 + Generated by: IHAVE (second stage)
27.6599 + Meaning: article transferred OK.
27.6600 +
27.6601 + Response code 240
27.6602 + Generated by: POST (second stage)
27.6603 + Meaning: article received OK.
27.6604 +
27.6605 +
27.6606 +
27.6607 +
27.6608 +Feather Standards Track [Page 118]
27.6609 +
27.6610 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6611 +
27.6612 +
27.6613 + Response code 335
27.6614 + Generated by: IHAVE (first stage)
27.6615 + Meaning: send article to be transferred.
27.6616 +
27.6617 + Response code 340
27.6618 + Generated by: POST (first stage)
27.6619 + Meaning: send article to be posted.
27.6620 +
27.6621 + Response code 400
27.6622 + Generic response and generated by initial connection
27.6623 + Meaning: service not available or no longer available (the server
27.6624 + immediately closes the connection).
27.6625 +
27.6626 + Response code 401
27.6627 + Generic response
27.6628 + 1 argument: capability-label
27.6629 + Meaning: the server is in the wrong mode; the indicated capability
27.6630 + should be used to change the mode.
27.6631 +
27.6632 + Response code 403
27.6633 + Generic response
27.6634 + Meaning: internal fault or problem preventing action being taken.
27.6635 +
27.6636 + Response code 411
27.6637 + Generated by: GROUP, LISTGROUP
27.6638 + Meaning: no such newsgroup.
27.6639 +
27.6640 + Response code 412
27.6641 + Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP,
27.6642 + NEXT, OVER, STAT
27.6643 + Meaning: no newsgroup selected.
27.6644 +
27.6645 + Response code 420
27.6646 + Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT
27.6647 + Meaning: current article number is invalid.
27.6648 +
27.6649 + Response code 421
27.6650 + Generated by: NEXT
27.6651 + Meaning: no next article in this group.
27.6652 +
27.6653 + Response code 422
27.6654 + Generated by: LAST
27.6655 + Meaning: no previous article in this group.
27.6656 +
27.6657 + Response code 423
27.6658 + Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
27.6659 + Meaning: no article with that number or in that range.
27.6660 +
27.6661 +
27.6662 +
27.6663 +
27.6664 +Feather Standards Track [Page 119]
27.6665 +
27.6666 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6667 +
27.6668 +
27.6669 + Response code 430
27.6670 + Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
27.6671 + Meaning: no article with that message-id.
27.6672 +
27.6673 + Response code 435
27.6674 + Generated by: IHAVE (first stage)
27.6675 + Meaning: article not wanted.
27.6676 +
27.6677 + Response code 436
27.6678 + Generated by: IHAVE (either stage)
27.6679 + Meaning: transfer not possible (first stage) or failed (second
27.6680 + stage); try again later.
27.6681 +
27.6682 + Response code 437
27.6683 + Generated by: IHAVE (second stage)
27.6684 + Meaning: transfer rejected; do not retry.
27.6685 +
27.6686 + Response code 440
27.6687 + Generated by: POST (first stage)
27.6688 + Meaning: posting not permitted.
27.6689 +
27.6690 + Response code 441
27.6691 + Generated by: POST (second stage)
27.6692 + Meaning: posting failed.
27.6693 +
27.6694 + Response code 480
27.6695 + Generic response
27.6696 + Meaning: command unavailable until the client has authenticated
27.6697 + itself.
27.6698 +
27.6699 + Response code 483
27.6700 + Generic response
27.6701 + Meaning: command unavailable until suitable privacy has been
27.6702 + arranged.
27.6703 +
27.6704 + Response code 500
27.6705 + Generic response
27.6706 + Meaning: unknown command.
27.6707 +
27.6708 + Response code 501
27.6709 + Generic response
27.6710 + Meaning: syntax error in command.
27.6711 +
27.6712 +
27.6713 +
27.6714 +
27.6715 +
27.6716 +
27.6717 +
27.6718 +
27.6719 +
27.6720 +Feather Standards Track [Page 120]
27.6721 +
27.6722 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6723 +
27.6724 +
27.6725 + Response code 502
27.6726 + Generic response and generated by initial connection
27.6727 +
27.6728 + Meaning for the initial connection and the MODE READER command:
27.6729 + service permanently unavailable (the server immediately closes the
27.6730 + connection).
27.6731 +
27.6732 + Meaning for all other commands: command not permitted (and there
27.6733 + is no way for the client to change this).
27.6734 +
27.6735 + Response code 503
27.6736 + Generic response
27.6737 + Meaning: feature not supported.
27.6738 +
27.6739 + Response code 504
27.6740 + Generic response
27.6741 + Meaning: error in base64-encoding [RFC4648] of an argument.
27.6742 +
27.6743 +Appendix D. Changes from RFC 977
27.6744 +
27.6745 + In general every attempt has been made to ensure that the protocol
27.6746 + specification in this document is compatible with the version
27.6747 + specified in RFC 977 [RFC977] and the various facilities adopted from
27.6748 + RFC 2980 [RFC2980]. However, there have been a number of changes,
27.6749 + some compatible and some not.
27.6750 +
27.6751 + This appendix lists these changes. It is not guaranteed to be
27.6752 + exhaustive or correct and MUST NOT be relied on.
27.6753 +
27.6754 + o A formal syntax specification (Section 9) has been added.
27.6755 +
27.6756 + o The default character set is changed from US-ASCII [ANSI1986] to
27.6757 + UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8). This
27.6758 + matter is discussed further in Section 10.
27.6759 +
27.6760 + o All articles are required to have a message-id, eliminating the
27.6761 + "<0>" placeholder used in RFC 977 in some responses.
27.6762 +
27.6763 + o The newsgroup name matching capabilities already documented in
27.6764 + RFC 977 ("wildmats", Section 4) are clarified and extended. The
27.6765 + new facilities (e.g., the use of commas and exclamation marks) are
27.6766 + allowed wherever wildmats appear in the protocol.
27.6767 +
27.6768 + o Support for pipelining of commands (Section 3.5) is made
27.6769 + mandatory.
27.6770 +
27.6771 +
27.6772 +
27.6773 +
27.6774 +
27.6775 +
27.6776 +Feather Standards Track [Page 121]
27.6777 +
27.6778 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6779 +
27.6780 +
27.6781 + o The principles behind response codes (Section 3.2) have been
27.6782 + tidied up. In particular:
27.6783 +
27.6784 + * the x8x response code family, formerly used for private
27.6785 + extensions, is now reserved for authentication and privacy
27.6786 + extensions;
27.6787 +
27.6788 + * the x9x response code family, formerly intended for debugging
27.6789 + facilities, are now reserved for private extensions;
27.6790 +
27.6791 + * the 502 and 503 generic response codes (Section 3.2.1) have
27.6792 + been redefined;
27.6793 +
27.6794 + * new 401, 403, 480, 483, and 504 generic response codes have
27.6795 + been added.
27.6796 +
27.6797 + o The rules for article numbering (Section 6) have been clarified
27.6798 + (also see Section 6.1.1.2).
27.6799 +
27.6800 + o The SLAVE command (which was ill-defined) is removed from the
27.6801 + protocol.
27.6802 +
27.6803 + o Four-digit years are permitted in the NEWNEWS (Section 7.4) and
27.6804 + NEWGROUPS (Section 7.3) commands (two-digit years are still
27.6805 + permitted). The optional distribution parameter to these commands
27.6806 + has been removed.
27.6807 +
27.6808 + o The LIST command (Section 7.6.1) is greatly extended; the original
27.6809 + is available as LIST ACTIVE, while new variants include
27.6810 + ACTIVE.TIMES, DISTRIB.PATS, and NEWSGROUPS. A new "m" status flag
27.6811 + is added to the LIST ACTIVE response.
27.6812 +
27.6813 + o A new CAPABILITIES command (Section 5.2) allows clients to
27.6814 + determine what facilities are supported by a server.
27.6815 +
27.6816 + o The DATE command (Section 7.1) is adopted from RFC 2980
27.6817 + effectively unchanged.
27.6818 +
27.6819 + o The LISTGROUP command (Section 6.1.2) is adopted from RFC 2980.
27.6820 + An optional range argument has been added, and the 211 initial
27.6821 + response line now has the same format as the 211 response from the
27.6822 + GROUP command.
27.6823 +
27.6824 + o The MODE READER command (Section 5.3) is adopted from RFC 2980 and
27.6825 + its meaning and effects clarified.
27.6826 +
27.6827 + o The XHDR command in RFC 2980 has been formalised as the new HDR
27.6828 + (Section 8.5) and LIST HEADERS (Section 8.6) commands.
27.6829 +
27.6830 +
27.6831 +
27.6832 +Feather Standards Track [Page 122]
27.6833 +
27.6834 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6835 +
27.6836 +
27.6837 + o The XOVER command in RFC 2980 has been formalised as the new OVER
27.6838 + (Section 8.3) and LIST OVERVIEW.FMT (Section 8.4) commands. The
27.6839 + former can be applied to a message-id as well as to a range.
27.6840 +
27.6841 + o The concept of article metadata (Section 8.1) has been formalised,
27.6842 + allowing the Bytes and Lines pseudo-headers to be deprecated.
27.6843 +
27.6844 + Client authors should note in particular that lack of support for the
27.6845 + CAPABILITIES command is a good indication that the server does not
27.6846 + support this specification.
27.6847 +
27.6848 +
27.6849 +
27.6850 +
27.6851 +
27.6852 +
27.6853 +
27.6854 +
27.6855 +
27.6856 +
27.6857 +
27.6858 +
27.6859 +
27.6860 +
27.6861 +
27.6862 +
27.6863 +
27.6864 +
27.6865 +
27.6866 +
27.6867 +
27.6868 +
27.6869 +
27.6870 +
27.6871 +
27.6872 +
27.6873 +
27.6874 +
27.6875 +
27.6876 +
27.6877 +
27.6878 +
27.6879 +
27.6880 +
27.6881 +
27.6882 +
27.6883 +
27.6884 +
27.6885 +
27.6886 +
27.6887 +
27.6888 +Feather Standards Track [Page 123]
27.6889 +
27.6890 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6891 +
27.6892 +
27.6893 +Author's Address
27.6894 +
27.6895 + Clive D.W. Feather
27.6896 + THUS plc
27.6897 + 322 Regents Park Road
27.6898 + London
27.6899 + N3 2QQ
27.6900 + United Kingdom
27.6901 +
27.6902 + Phone: +44 20 8495 6138
27.6903 + Fax: +44 870 051 9937
27.6904 + EMail: clive@demon.net
27.6905 + URI: http://www.davros.org/
27.6906 +
27.6907 +
27.6908 +
27.6909 +
27.6910 +
27.6911 +
27.6912 +
27.6913 +
27.6914 +
27.6915 +
27.6916 +
27.6917 +
27.6918 +
27.6919 +
27.6920 +
27.6921 +
27.6922 +
27.6923 +
27.6924 +
27.6925 +
27.6926 +
27.6927 +
27.6928 +
27.6929 +
27.6930 +
27.6931 +
27.6932 +
27.6933 +
27.6934 +
27.6935 +
27.6936 +
27.6937 +
27.6938 +
27.6939 +
27.6940 +
27.6941 +
27.6942 +
27.6943 +
27.6944 +Feather Standards Track [Page 124]
27.6945 +
27.6946 +RFC 3977 Network News Transfer Protocol (NNTP) October 2006
27.6947 +
27.6948 +
27.6949 +Full Copyright Statement
27.6950 +
27.6951 +Copyright (C) The Internet Society (2006).
27.6952 +
27.6953 + This document is subject to the rights, licenses and restrictions
27.6954 + contained in BCP 78, and except as set forth therein, the authors
27.6955 + retain all their rights.
27.6956 +
27.6957 + This document and the information contained herein are provided on an
27.6958 + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
27.6959 + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
27.6960 + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
27.6961 + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
27.6962 + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
27.6963 + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
27.6964 +
27.6965 +Intellectual Property
27.6966 +
27.6967 + The IETF takes no position regarding the validity or scope of any
27.6968 + Intellectual Property Rights or other rights that might be claimed to
27.6969 + pertain to the implementation or use of the technology described in
27.6970 + this document or the extent to which any license under such rights
27.6971 + might or might not be available; nor does it represent that it has
27.6972 + made any independent effort to identify any such rights. Information
27.6973 + on the procedures with respect to rights in RFC documents can be
27.6974 + found in BCP 78 and BCP 79.
27.6975 +
27.6976 + Copies of IPR disclosures made to the IETF Secretariat and any
27.6977 + assurances of licenses to be made available, or the result of an
27.6978 + attempt made to obtain a general license or permission for the use of
27.6979 + such proprietary rights by implementers or users of this
27.6980 + specification can be obtained from the IETF on-line IPR repository at
27.6981 + http://www.ietf.org/ipr.
27.6982 +
27.6983 + The IETF invites any interested party to bring to its attention any
27.6984 + copyrights, patents or patent applications, or other proprietary
27.6985 + rights that may cover technology that may be required to implement
27.6986 + this standard. Please address the information to the IETF at ietf-
27.6987 + ipr@ietf.org.
27.6988 +
27.6989 +Acknowledgement
27.6990 +
27.6991 + Funding for the RFC Editor function is provided by the IETF
27.6992 + Administrative Support Activity (IASA).
27.6993 +
27.6994 +
27.6995 +
27.6996 +
27.6997 +
27.6998 +
27.6999 +
27.7000 +Feather Standards Track [Page 125]
27.7001 +
28.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
28.2 +++ b/trunk/test/StringTemplateTest.java Tue Jan 20 10:21:03 2009 +0100
28.3 @@ -0,0 +1,26 @@
28.4 +/*
28.5 + * To change this template, choose Tools | Templates
28.6 + * and open the template in the editor.
28.7 + */
28.8 +
28.9 +package test;
28.10 +
28.11 +import com.so.news.util.StringTemplate;
28.12 +
28.13 +/**
28.14 + *
28.15 + * @author chris
28.16 + */
28.17 +public class StringTemplateTest
28.18 +{
28.19 + public static void main(String[] args)
28.20 + {
28.21 + StringTemplate templ
28.22 + = new StringTemplate("SELECT %row FROM %table WHERE %row = ich");
28.23 +
28.24 + templ.set("row", "name");
28.25 + templ.set("table", "UserTable");
28.26 +
28.27 + System.out.println(templ.toString());
28.28 + }
28.29 +}